Skip to content

Commit

Permalink
Merge branch 'staging-26-2017'
Browse files Browse the repository at this point in the history
  • Loading branch information
joelillo committed Feb 23, 2017
2 parents a4f1809 + ec14f28 commit a58d6eb
Show file tree
Hide file tree
Showing 51 changed files with 1,994 additions and 2,406 deletions.
17 changes: 17 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
VERSION := $(shell git describe --always --long --dirty)
GOPATH := $(GOPATH)
BINARY := rita

LDFLAGS=-ldflags="-X github.com/ocmdev/rita/config.VERSION=${VERSION}"


default:
go get
go build ${LDFLAGS}

# Having issues with 'go install' + LDFLAGS using sudo and the
# install script. This is a workaround.
install:
go get
go build ${LDFLAGS} -o ${GOPATH}/bin/${BINARY}

170 changes: 62 additions & 108 deletions Readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,122 +2,76 @@

Brought to you by Offensive CounterMeasures

###Disclaimer
###What's here

RITA is not production ready! This software is being released open source as it
is being worked on. The team at OCM (Offensive CounterMeasures) has been
diligently working on the process of separating the analysis logic from the
front end which is destined to be product for sale by Offensive CounterMeasures.
RITA is an open source network traffic analysis framework.

###Current state
The framework ingests [Bro Logs](https://www.bro.org/), and currently supports the following analysis features:
- **Beaconing**: Search for signs of beaconing behavior in and out of your network
- **Blacklisted**: Query blacklists to search for suspicious domains and hosts in your network traffic
- **Scanning**: Search for signs of port scans in your network

####Terminal output
Right now we're working on getting output that makes getting your analysis data
easy and follows common unix ideas. Ideally this output will eventually be fully
compatible with the formatting of bro's logs which should make working with the
output much easier for those already versed in the useage of tools like bro-cut.
This feature is being worked on.
Additional functionality is being developed and will be included soon.

####Graphical front end
We're also working on getting a minimalist front end to the platform that can
be used to simply avoid the command line. This will probably take longer than
the above and should not be expected to have the data visualization features
present in the AI Hunt project.

###What's here
### Automatic Installation
**The automatic RITA installer is officially supported on Ubuntu 16.04 LTS**

Clone the package:
```bash
git clone https://github.com/ocmdev/rita.git
```

Change into the source directory:
```bash
cd rita
```
Run the installer:

**Note:**
By default, Rita will install to /usr/local/rita.
However, you can change the install location with the *-i* flag.
```bash
sudo ./install.sh
```

***or***

```bash
sudo ./install.sh -i /path/to/install/directory
```

### Manual Installation
To install each component of Rita by hand, [check out the instructions in the wiki](https://github.com/ocmdev/rita/wiki/Installation).

### Configuration File
RITA contains a yaml format configuration file.

You can specify the location for the configuration file with the **-c** command line flag. If not specified, RITA will first look for the configuration in **~/.rita/config.yaml** then **/etc/rita/config.yaml**.


### API Keys
Rita relies on the the [Google Safe Browsing API](https://developers.google.com/safe-browsing/) to check network log data for connections to known threats. An API key is required to use this service. Obtaining a key is free, and only requires a Google account.

To obtain an API key:
* Go to the [cloud platform console](https://console.cloud.google.com/).
* From the projects list, select a project or create a new one.
* If the API Manager page isn't already open, open the left side menu and select **API Manager**.
* On the left, choose **Credentials**.
* Click **Create credentials** and then select **API key**.
* Copy this API key to the **APIKey** field under **SafeBrowsing** in the configuration file.
* On the left, choose **Library**.
* Search for **Safe Browsing**.
* Click on **Google Safe Browsing API**.
* Near the top, click **Enable**.

Now replace the **APIKey** field under **SafeBrowsing** in the configuration file with the obtained key.

RITA has all of the logic used to analyze Bro data. With an input of Bro data a
MongoDB database will be created, which can be analyzed for review of that data.
All of the mathematics, lookups, and storage of Offensive CounterMeasures AI
Hunter is available in this package. The only thing not here is the graphical
front end which Offensive CounterMeasures has created to help visualize this
data.

###Installation

1. What you'll need:
* Bro [https://www.bro.org](https://www.bro.org)
* MongoDB [https://www.mongodb.com](https://www.mongodb.com)
* Golang [https://www.golang.org](https://www.golang.org)
* GNU netcat [http://netcat.sourceforge.net/](http://netcat.sourceforge.net/)

1. Setting up your environment:
1. Install bro using the directions at [https://www.bro.org/sphinx/install/install.html](https://www.bro.org/sphinx/install/install.html)
1. Test that bro is working by firing up bro and ensuring that it's spitting out logs. If you're having some trouble
with bro configuration or use here are some helpful links:
* Bro quick start [https://www.bro.org/sphinx-git/quickstart/index.html](https://www.bro.org/sphinx-git/quickstart/index.html)
* broctl [https://www.bro.org/sphinx/components/broctl/README.html](https://www.bro.org/sphinx/components/broctl/README.html)
1. Install MongoDB (You will need MongoDB 3.2.0 which is not included in the Ubuntu 16.04 package manager. If you use your package manager, make sure it is at least MongoDB version 3.x)
* Download 3.2.0 at https://www.mongodb.com/download-center?jmp=nav#community
* Select your version of linux and download the package
1. Install GNU Netcat, make sure that it is GNU Netcat. NC will not work. [http://netcat.sourceforge.net/](http://netcat.sourceforge.net/)
1. Install GoLang using the instructions at [https://golang.org/doc/install](https://golang.org/doc/install)
1. After the install we need to set a local GOPATH for our user. So lets set up a directory in our HomeDir
* ```mkdir -p $HOME/go/{src,pkg,bin}```
1. Now we must add the GoPath to our .bashrc file
* ```echo 'export GOPATH="$HOME/go"' >> $HOME/.bashrc```
1. We will also want to add our bin folder to the path for this user.
* ```echo 'export PATH="$PATH:$GOPATH/bin"' >> $HOME/.bashrc```
1. Load your new configurations with source.
* ```source $HOME/.bashrc```

1. Getting the sources and building them
1. First we want to use the go to grab sources and deps for rita.
* ```go get github.com/ocmdev/rita```
1. Now lets change to the rita directory.
* ```cd $GOPATH/src/github.com/ocmdev/rita```
1. Then build rita.
* ```go build```
1. Now we'll install the rita binary.
* ```go install```
1. Finally, let's install all of the supporting software.
* ```sudo ./install.sh```

1. Configuring MongoDB
1. If your package manager automatically installs and configures the latest MongoDB 3.x, you can skip this section
1. Unzip the file you downloaded earlier
* ```tar -zxvf mongodb-linux-x86_64-[your OS version].tgz```
1. Copy the directory to it's own folder, this is where the MongoDB process will run
* ```mkdir -p <path_to_desired_folder>/mongodb && cp -R -n mongodb-linux-x86_64-3.2.10/ <path_to_desired_folder>/mongodb```
1. Ensure this location is set in your path variable, this can be done quickly with
* ```echo 'export PATH="<your_mongodb_install_directory>/mongodb-linux-x86_64-<linux version>-3.2.10/bin:$PATH"' >> ~/.bashrc```
1. Load your new bash config
* ```source $HOME/.bashrc```

1. Launching MongoDB
1. Again if your package manager automatically installs and configures MongoDB 3.x, you can skip this section
1. Make your MongoDB directory, usually /data/db
* ```sudo mkdir -p /data/db```
1. Then give the user permissions to read/write to our database directory
* ```sudo chown -R <username> /data```
1. Now at this point you can watch MongoDB do it's magic before your very eyes with
* ```mongod```
1. Otherwise if you're a very busy person like us, you can fork the process as a daemon. Make the log file and grant appropriate permissions
* ```sudo touch /data/mongod.log && sudo chown <username> mongod.log && sudo chmod u+w /data/mongod.log```
1. Then start mongod daemon with
* ```mongod --fork --logpath /data/mongod.log -f /etc/mongod.conf```
1. If mongo is still not running, you can check out further documentation at https://docs.mongodb.com/

1. Configuring the system
1. If you installed as sudo (root) then there will be a default config file at both /usr/local/rita/etc/rita.yaml
and /etc/rita/config.yaml.
1. You can also copy the global config from /etc to your homedir and call it .rita. If there's a .rita config that's
the one that will be used. Here's the order of precendence for configuration.
* file given on the command line with the -c flag
* $HOME/.rita
* /etc/rita/config.yaml
* If none of the above files successfully configure the system then the system fails.
1. You can test a configuration file with ```rita testconfig PATH/TO/FILE``` if the file is syntactically correct rita
will print the resultant configuration. If it fails an error will be given.
1. The most important parts of the configuration file are the database path, the path for your netcat binary, a name
for the database you'd like to create with this dataset, and of course the Bro section of the yaml file which configures
your parser. There are comments in the yaml file that should help with configuration.
### Getting Started
**Link to video tutorial will be added soon!**

###Getting help
Head over to OFTC and join #ocmdev for any questions you may have. Please
remember that this is an open source project, the developers working in here
have full time jobs and are not your personal tech support. So please be civil
with us.
Head over to OFTC and join #ocmdev for any questions you may have.

###License
GNU GPL V3
Expand Down
Loading

0 comments on commit a58d6eb

Please sign in to comment.