README.Rmd

---
output: rmarkdown::github_document
editor_options: 
  chunk_output_type: console
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, echo = FALSE}
knitr::opts_chunk$set(collapse=TRUE, comment="##", fig.retina=2, fig.path = "README_figs/README-", message=FALSE, warning=FALSE)
options(width=120)
```

    __________________________oooo__oo____________________
    _ooooo__oo_ooo___ooooo___oo_____oo_____ooooo__oo_ooo__
    oo___oo_ooo___o_oo___oo_ooooo__oooo___oo____o_ooo___o_
    oo______oo______oo___oo_oo______oo____ooooooo_oo______
    oo______oo______oo___oo_oo______oo__o_oo______oo______
    _ooooo__oo_______oooo_o_oo_______ooo___ooooo__oo______
    ______________________________________________________
  
# crafter

Tools to Analyze and Visualize Network Packet Capture (PCAP) Files

## Description

Life's too short to export to CSV/XML. There's no reason R should not be able to read binary PCAP data.

[What is a PCAP?](https://en.wikipedia.org/wiki/Pcap)

You need the [crafter C++ library](https://github.com/pellegre/libcrafter) installed and their site lists the other dependencies.

If there's any hope for this to run on Windows (`libcrafter` supports Windows) it will be due to a Windows + (prbly some infosec) + `#rstats` person tagging along on this project.

You can find some sample PCAP files:

- [Netresec](http://www.netresec.com/?page=PcapFiles)
- [Wireshark](https://wiki.wireshark.org/SampleCaptures)

## What's Inside The Tin?

The following functions are implemented:

- `read_pcap`:	Read in a packet capture file
- `seq_in`:	Find a (the first) sequence in a vector
- `summary.crafter`:	Print summary info about a packet capture

(The `pcap` in the functions below is the return value from a call to `read_pcap`.)

- `pcap$get_layer`: return a data.frame with the indicated protocol layer from the pcap packets
- `pcap$packet_info`: retrieve a data frame of high level packet info
- `pcap$get_payload`: retrieve payload (if any) from a given packet number
- `pcap$get_ips`: retrieve a list (with counts) of src/dst/all ips in the capture
- `pcap$summary`: summary info about the capture

(There are actually more but they're inside the pcap object and I just need to get them exposed. See the example below for usage.)

## Installation

```{r eval=FALSE}
devtools::install_github("hrbrmstr/crafter")
```

## Usage

```{r}
library(crafter)

# current verison
packageVersion("crafter")

library(crafter)
library(dplyr)
library(ggplot2)
library(igraph)

# read in the "honeybot" packet capture from the "Capture the hacker 2013"
# competition (by Dr. David Day of Sheffield Hallam University) http://www.snaketrap.co.uk/
hbot <- read_pcap(system.file("pcaps/hbot.pcap", package="crafter"))

# high level statistics
summary(hbot)

# look at general packet info
head(hbot$packet_info(), 15)

# look at the IP layer packets
hbot_ip <- hbot$get_layer("IP")

# have some semi-useless fun!
pairs <- count(hbot_ip, src, dst, protocol_name)

nodes <- unique(c(pairs$src, pairs$dst))

g <- graph_from_data_frame(pairs, directed=TRUE, vertices=nodes)
```

```{r fig.width=10, fig.height=10}
plot(g, layout=layout.circle, vertex.size=sqrt(degree(g)), 
     vertex.label=NA, edge.width=0.5, edge.arrow.width=0.5, edge.arrow.size=0.5)
```

```{r}
# look at the data
head(hbot_ip, 10)

# look at the TCP layer packets
head(hbot$get_layer("TCP"), 5)

# this is probably a bit more useful
hbot_tcp <- hbot$get_layer("TCP")

src <- "192.168.0.200"
dst <- "91.199.212.171"

hbot_tcp %>% 
  filter((src==src & dst==dst) |
         (src==dst | dst == src)) %>% 
  select(payload) -> pays

cat(paste0(pays$payload[1:25], collapse="\n"))

# look at the ICMP layer packets
head(hbot$get_layer("ICMP"), 20)

# see the protocol distribution
hbot$get_layer("IP") %>% 
  count(protocol_name) %>% 
  ggplot(aes(x=protocol_name, y=n)) + 
  geom_bar(stat="identity") + 
  labs(x=NULL, title="Honeybot IP Protocols") + 
  theme_bw()

```

## Code of Conduct

Please note that this project is released with a [Contributor Code of Conduct](CONDUCT.md). 
By participating in this project you agree to abide by its terms.