Skip to content

Branch Adjustments, Terminology Updates #833

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lisaSW merged 1 commit into from
Jan 10, 2026
Merged

Branch Adjustments, Terminology Updates #833

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 39 additions & 29 deletions Contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,55 +1,65 @@
# Contributing to RITA

---

## Want to help? We would love that!

Here are some ways to get involved, ranging in
difficulty from easiest to hardest

## Bug Hunting

Run the software and tell us when it breaks. We are happy to receive bug
reports

Just be sure to do the following:
* Check if the bug is already accounted for on the
[Github issue tracker](https://github.com/activecm/rita/issues)
* If an issue already exists, add the relevant info in a comment
* If not, create an issue and include the relevant info
* Give very specific descriptions of how to reproduce the bug
* Include the output of `rita --version`
* Include a description of your hardware (e.g. CPU, RAM, filesystems)
* Tell us about the size of the test and the physical resources available

- Check if the bug is already accounted for on the
[Github issue tracker](https://github.com/activecm/rita/issues)
- If an issue already exists, add the relevant info in a comment
- If not, create an issue and include the relevant info
- Give very specific descriptions of how to reproduce the bug
- Include the output of `rita --version`
- Include a description of your hardware (e.g. CPU, RAM, filesystems)
- Tell us about the size of the test and the physical resources available

## Contributing Code

There are several ways to contribute code to the RITA project.
Before diving in, follow the [Manual Installation Instructions](docs/Manual%20Installation.md)

* Work on bug fixes:
* Find an issue you would like to work on in the Github tracker, especially [unassigned issues marked "good first issue"](https://github.com/activecm/rita/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+no%3Aassignee)
* Leave a comment letting us know you would like to work on it
* Add new features:
* If you would like to become involved in the development effort, open a new issue or continue a discussion on an existing issue
- Work on bug fixes:
- Find an issue you would like to work on in the Github tracker, especially [unassigned issues marked "good first issue"](https://github.com/activecm/rita/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+no%3Aassignee)
- Leave a comment letting us know you would like to work on it
- Add new features:
- If you would like to become involved in the development effort, open a new issue or continue a discussion on an existing issue

### Running Static Tests
* You must have a RITA [development environment](https://github.com/activecm/rita/blob/master/docs/Manual%20Installation.md#installing-golang) set up and [golangci-lint](https://github.com/golangci/golangci-lint#install) installed to run the tests.
* Check the [Makefile](https://github.com/activecm/rita/blob/master/Makefile) for all options. Currently you can run `make test`, `make static-test`, and `make unit-test`. There is also `make integration-test` and docker variants that will require you install docker as well.

- You must have a RITA [development environment](https://github.com/activecm/rita-legacy/blob/main/docs/Manual%20Installation.md#installing-golang) set up and [golangci-lint](https://github.com/golangci/golangci-lint#install) installed to run the tests.
- Check the [Makefile](https://github.com/activecm/rita-legacy/blob/main/Makefile) for all options. Currently you can run `make test`, `make static-test`, and `make unit-test`. There is also `make integration-test` and docker variants that will require you install docker as well.

### Reviewing Automated Test Results
Automated tests are run against each pull request. Build results may be viewed [here](https://github.com/activecm/rita/actions).

Automated tests are run against each pull request. Build results may be viewed [here](https://github.com/activecm/rita-legacy/actions).

### Gittiquette Summary
* In order to contribute to RITA, you must [fork it](https://github.com/activecm/rita/fork).
* Once you have a forked repo you will need to clone it to a very specific path which corresponds to _the original repo location_. This is due to the way packages are imported in Go programs.
* `git clone [your forked repo git url]`
* Add `https://github.com/activecm/rita` as a new remote so you can pull new changes.
* `git remote add upstream https://github.com/activecm/rita`
* Split a branch off of master .
* `git checkout -b [your new feature]`
* When your work is finished, pull the latest changes from the upstream master and rebase your changes on it.
* `git checkout master; git pull -r upstream master`
* `git checkout [your new feature]; git rebase master`
* Push your commits to your repo and submit a pull request on Github.

- In order to contribute to RITA, you must [fork it](https://github.com/activecm/rita-legacy/fork).
- Once you have a forked repo you will need to clone it to a very specific path which corresponds to _the original repo location_. This is due to the way packages are imported in Go programs.
- `git clone [your forked repo git url]`
- Add `https://github.com/activecm/rita-legacy` as a new remote so you can pull new changes.
- `git remote add upstream https://github.com/activecm/rita-legacy`
- Split a branch off of main.
- `git checkout -b [your new feature]`
- When your work is finished, pull the latest changes from the upstream main and rebase your changes on it.
- `git checkout main; git pull -r upstream main`
- `git checkout [your new feature]; git rebase main`
- Push your commits to your repo and submit a pull request on Github.

Further info can be found in the [Gittiquette doc](docs/RITA%20Gittiquette.md) under the guidelines and contributors sections.

### Common Issues
* Building Rita using `go build` or `go install` yields a RITA version of `UNDEFINED`
* Use `make` or `make install` instead

- Building Rita using `go build` or `go install` yields a RITA version of `UNDEFINED`
- Use `make` or `make install` instead
97 changes: 51 additions & 46 deletions Readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,10 @@ Sponsored by [Active Countermeasures](https://activecountermeasures.com/).
RITA is an open source framework for network traffic analysis.

The framework ingests [Zeek Logs](https://www.zeek.org/) in TSV format, and currently supports the following major features:
- **Beaconing Detection**: Search for signs of beaconing behavior in and out of your network
- **DNS Tunneling Detection** Search for signs of DNS based covert channels
- **Blacklist Checking**: Query blacklists to search for suspicious domains and hosts

- **Beaconing Detection**: Search for signs of beaconing behavior in and out of your network
- **DNS Tunneling Detection** Search for signs of DNS based covert channels
- **Blacklist Checking**: Query blacklists to search for suspicious domains and hosts

## Install

Expand All @@ -27,11 +28,11 @@ Download the latest `install.sh` file [here](https://github.com/activecm/rita/re

Then choose one of the following install methods:

* `sudo ./install.sh` will install RITA as well as supported versions of Zeek and MongoDB. This is suitable if you want to get started as quickly as possible or you don't already have Zeek or MongoDB.
- `sudo ./install.sh` will install RITA as well as supported versions of Zeek and MongoDB. This is suitable if you want to get started as quickly as possible or you don't already have Zeek or MongoDB.

* `sudo ./install.sh --disable-zeek --disable-mongo` will install RITA only, without Zeek or MongoDB. You may also use these flags individually.
* If you choose not to install Zeek you will need to [provide your own logs](#obtaining-data-generating-zeek-logs).
* If you choose not to install MongoDB you will need to configure RITA to [use your existing MongoDB server](docs/Mongo%20Configuration.md).
- `sudo ./install.sh --disable-zeek --disable-mongo` will install RITA only, without Zeek or MongoDB. You may also use these flags individually.
- If you choose not to install Zeek you will need to [provide your own logs](#obtaining-data-generating-zeek-logs).
- If you choose not to install MongoDB you will need to configure RITA to [use your existing MongoDB server](docs/Mongo%20Configuration.md).

### Docker Install

Expand All @@ -51,35 +52,41 @@ See [this guide](docs/Upgrading.md) for upgrade instructions.

RITA's config file is located at `/etc/rita/config.yaml` though you can specify a custom path on individual commands with the `-c` command line flag.

* The `Filtering: InternalSubnets` section *must* be configured or you will not see any results in certain modules (e.g. beacons, long connections). If your network uses the standard RFC1918 internal IP ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) you don't need to do anything as the default `InternalSubnets` section already has these. Otherwise, adjust this section to match your environment. RITA's main purpose is to find the signs of a compromised internal system talking to an external system and will automatically exclude internal to internal connections and external to external connections from parts of the analysis.
- The `Filtering: InternalSubnets` section _must_ be configured or you will not see any results in certain modules (e.g. beacons, long connections). If your network uses the standard RFC1918 internal IP ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) you don't need to do anything as the default `InternalSubnets` section already has these. Otherwise, adjust this section to match your environment. RITA's main purpose is to find the signs of a compromised internal system talking to an external system and will automatically exclude internal to internal connections and external to external connections from parts of the analysis.

You may also wish to change the defaults for the following option:
* `Filtering: AlwaysInclude` - Ranges listed here are exempt from the filtering applied by the `InternalSubnets` setting. The main use for this is to include internal DNS servers so that you can see the source of any DNS queries made.

- `Filtering: AlwaysInclude` - Ranges listed here are exempt from the filtering applied by the `InternalSubnets` setting. The main use for this is to include internal DNS servers so that you can see the source of any DNS queries made.

Note that any value listed in the `Filtering` section should be in CIDR format. So a single IP of `192.168.1.1` would be written as `192.168.1.1/32`.

#### Obtaining Data (Generating Zeek Logs)

* **Option 1**: Generate PCAPs outside of Zeek
* Generate PCAP files with a packet sniffer ([tcpdump](http://www.tcpdump.org/), [wireshark](https://www.wireshark.org/), etc.)
* (Optional) Merge multiple PCAP files into one PCAP file
* `mergecap -w outFile.pcap inFile1.pcap inFile2.pcap`
* Generate Zeek logs from the PCAP files
* ```zeek -r pcap_to_log.pcap local "Log::default_rotation_interval = 1 day"```
- **Option 1**: Generate PCAPs outside of Zeek

- Generate PCAP files with a packet sniffer ([tcpdump](http://www.tcpdump.org/), [wireshark](https://www.wireshark.org/), etc.)
- (Optional) Merge multiple PCAP files into one PCAP file
- `mergecap -w outFile.pcap inFile1.pcap inFile2.pcap`
- Generate Zeek logs from the PCAP files
- `zeek -r pcap_to_log.pcap local "Log::default_rotation_interval = 1 day"`

- **Option 2**: Install Zeek and let it monitor an interface directly [[instructions](https://docs.zeek.org/en/master/quickstart/index.html)]

- You may wish to [compile Zeek from source](https://docs.zeek.org/en/master/install/install.html) for performance reasons. [This script](https://github.com/activecm/bro-install) can help automate the process.
- The automated installer for RITA installs pre-compiled Zeek binaries by default
- Provide the `--disable-zeek` flag when running the installer if you intend to compile Zeek from source
- To take advantage of the feature for monitoring long-running, open connections (default is 1 hour or more), you will need to install our [zeek-open-connections plugin](https://github.com/activecm/zeek-open-connections/). We recommend installing the package with Zeek's package manager _zkg_. Newer versions of Zeek (4.0.0 or greater) will come bundled with _zkg_. If you do not have _zkg_ installed, you can [manually install](https://docs.zeek.org/projects/package-manager/en/stable/quickstart.html) it. Once you have _zkg_ installed, run the following commands to install the package

* **Option 2**: Install Zeek and let it monitor an interface directly [[instructions](https://docs.zeek.org/en/master/quickstart/index.html)]
* You may wish to [compile Zeek from source](https://docs.zeek.org/en/master/install/install.html) for performance reasons. [This script](https://github.com/activecm/bro-install) can help automate the process.
* The automated installer for RITA installs pre-compiled Zeek binaries by default
* Provide the `--disable-zeek` flag when running the installer if you intend to compile Zeek from source
* To take advantage of the feature for monitoring long-running, open connections (default is 1 hour or more), you will need to install our [zeek-open-connections plugin](https://github.com/activecm/zeek-open-connections/). We recommend installing the package with Zeek's package manager _zkg_. Newer versions of Zeek (4.0.0 or greater) will come bundled with _zkg_. If you do not have _zkg_ installed, you can [manually install](https://docs.zeek.org/projects/package-manager/en/stable/quickstart.html) it. Once you have _zkg_ installed, run the following commands to install the package
* ```zkg refresh```
* ```zkg install zeek/activecm/zeek-open-connections```
- `zkg refresh`
- `zkg install zeek/activecm/zeek-open-connections`

Next, edit your site/local.zeek file so that it contains the following line
* ```@load packages ```
Next, edit your site/local.zeek file so that it contains the following line

Finally, run the following
* ```zeekctl deploy```
- `@load packages `

Finally, run the following

- `zeekctl deploy`

#### Importing and Analyzing Data With RITA

Expand Down Expand Up @@ -117,30 +124,28 @@ rita import --rolling /opt/zeek/logs/$(date --date='-1 hour' +\%Y-\%m-\%d)/ data

RITA cycles data into and out of rolling databases in "chunks". You can think of each chunk as one hour, and the default being 24 chunks in a dataset. This gives the ability to always have the most recent 24 hours' worth of data available. But chunks are generic enough to accommodate non-default Zeek logging configurations or data retention times as well. See the [Rolling Datasets](docs/Rolling%20Datasets.md) documentation for advanced options.


> :grey_exclamation: **Note:** `dataset_name` is simply a name of your choosing. We recommend a descriptive name such as the hostname or location of where the data was captured. Stick with letters, numbers, and underscores. Periods and other special characters are not allowed.


#### Examining Data With RITA

* Use the **show-X** commands
* `show-databases`: Print the datasets currently stored
* `show-beacons`: Print hosts which show signs of C2 software
* `show-bl-hostnames`: Print blacklisted hostnames which received connections
* `show-bl-source-ips`: Print blacklisted IPs which initiated connections
* `show-bl-dest-ips`: Print blacklisted IPs which received connections
* `show-exploded-dns`: Print dns analysis. Exposes covert dns channels
* `show-long-connections`: Print long connections and relevant information
* `show-strobes`: Print connections which occurred with excessive frequency
* `show-useragents`: Print user agent information
* By default, RITA displays data in CSV format
* `-d [DELIM]` delimits the data by `[DELIM]` instead of a comma
* Strings can be provided instead of single characters if desired, e.g. `rita show-beacons -d "---" dataset_name`
* `-H` displays the data in a human readable format
* This takes precedence over the `-d` option
* Piping the human readable results through `less -S` prevents word wrapping
* Ex: `rita show-beacons dataset_name -H | less -S`
* Create a html report with `html-report`
- Use the **show-X** commands
- `show-databases`: Print the datasets currently stored
- `show-beacons`: Print hosts which show signs of C2 software
- `show-bl-hostnames`: Print blacklisted hostnames which received connections
- `show-bl-source-ips`: Print blacklisted IPs which initiated connections
- `show-bl-dest-ips`: Print blacklisted IPs which received connections
- `show-exploded-dns`: Print dns analysis. Exposes covert dns channels
- `show-long-connections`: Print long connections and relevant information
- `show-strobes`: Print connections which occurred with excessive frequency
- `show-useragents`: Print user agent information
- By default, RITA displays data in CSV format
- `-d [DELIM]` delimits the data by `[DELIM]` instead of a comma
- Strings can be provided instead of single characters if desired, e.g. `rita show-beacons -d "---" dataset_name`
- `-H` displays the data in a human readable format
- This takes precedence over the `-d` option
- Piping the human readable results through `less -S` prevents word wrapping
- Ex: `rita show-beacons dataset_name -H | less -S`
- Create a html report with `html-report`

### Getting help

Expand Down
4 changes: 2 additions & 2 deletions config/running.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,8 +64,8 @@ func initRunningConfig(static *StaticCfg, running *RunningCfg) error {
if err != nil {
fmt.Println("\t[!] Version error: please ensure that you cloned the git repo and are using make to build.")
fmt.Println("\t[!] See the following resources for further information:")
fmt.Println("\t[>] https://github.com/activecm/rita/blob/master/Contributing.md#common-issues")
fmt.Println("\t[>] https://github.com/activecm/rita/blob/master/docs/Manual%20Installation.md")
fmt.Println("\t[>] https://github.com/activecm/rita-legacy/blob/main/Contributing.md#common-issues")
fmt.Println("\t[>] https://github.com/activecm/rita-legacy/blob/main/docs/Manual%20Installation.md")
}
return err
}
Loading
Loading