From 1a35461eab49c71b1e634d411282bde999d65a33 Mon Sep 17 00:00:00 2001 From: hrbrmstr Date: Sat, 16 Mar 2019 15:42:37 -0400 Subject: [PATCH] initial commit --- .Rbuildignore | 1 + DESCRIPTION | 8 ++- NAMESPACE | 8 +++ R/aaa.R | 7 +++ R/api-key.R | 36 ++++++++++++ R/detail.R | 30 ++++++++++ R/download.R | 55 ++++++++++++++++++ R/graph.R | 46 +++++++++++++++ R/info.R | 30 ++++++++++ R/packettotal-package.R | 15 ++++- R/random.R | 28 +++++++++ R/search.R | 32 +++++++++++ R/usage.R | 27 +++++++++ README.Rmd | 46 ++++++++++++++- README.md | 140 +++++++++++++++++++++++++++++++++++++++++++++ man/packettotal.Rd | 16 +++++- man/packettotal_api_key.Rd | 23 ++++++++ man/pt_detail.Rd | 23 ++++++++ man/pt_download.Rd | 34 +++++++++++ man/pt_info.Rd | 23 ++++++++ man/pt_random.Rd | 20 +++++++ man/pt_search.Rd | 22 +++++++ man/pt_similar.Rd | 31 ++++++++++ man/pt_usage.Rd | 17 ++++++ 24 files changed, 710 insertions(+), 8 deletions(-) create mode 100644 R/aaa.R create mode 100644 R/api-key.R create mode 100644 R/detail.R create mode 100644 R/download.R create mode 100644 R/graph.R create mode 100644 R/info.R create mode 100644 R/random.R create mode 100644 R/search.R create mode 100644 R/usage.R create mode 100644 man/packettotal_api_key.Rd create mode 100644 man/pt_detail.Rd create mode 100644 man/pt_download.Rd create mode 100644 man/pt_info.Rd create mode 100644 man/pt_random.Rd create mode 100644 man/pt_search.Rd create mode 100644 man/pt_similar.Rd create mode 100644 man/pt_usage.Rd diff --git a/.Rbuildignore b/.Rbuildignore index ece4c73..9623512 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -2,6 +2,7 @@ ^.*\.Rproj$ ^\.Rproj\.user$ ^\.travis\.yml$ +^CONDUCT\.md$ ^README\.*Rmd$ ^README\.*html$ ^NOTES\.*Rmd$ diff --git a/DESCRIPTION b/DESCRIPTION index 3f2b7c1..f19fdf2 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: packettotal Type: Package -Title: packettotal title goes here otherwise CRAN checks fail +Title: Lookup and Analyze Packet Capture ('PCAP') Files Version: 0.1.0 Date: 2019-03-16 Authors@R: c( @@ -8,7 +8,11 @@ Authors@R: c( comment = c(ORCID = "0000-0001-5670-2640")) ) Maintainer: Bob Rudis -Description: A good description goes here otherwise CRAN checks fail. +Description: 'PacketTotal' () is an engine for analyzing, + categorizing, and sharing packet capture ('PCAP') files. The tool was built + with the information security community in mind and has applications in malware + analysis and network forensics. Methods are provided to query search for and + analyze packet capture files. URL: https://gitlab.com/hrbrmstr/packettotal BugReports: https://gitlab.com/hrbrmstr/packettotal/issues Encoding: UTF-8 diff --git a/NAMESPACE b/NAMESPACE index 5b4b9ae..1671ccf 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,4 +1,12 @@ # Generated by roxygen2: do not edit by hand +export(packettotal_api_key) +export(pt_detail) +export(pt_download) +export(pt_info) +export(pt_random) +export(pt_search) +export(pt_similar) +export(pt_usage) import(httr) importFrom(jsonlite,fromJSON) diff --git a/R/aaa.R b/R/aaa.R new file mode 100644 index 0000000..93aed6b --- /dev/null +++ b/R/aaa.R @@ -0,0 +1,7 @@ +httr::user_agent( + sprintf( + "packettotal package v%s: (<%s>)", + utils::packageVersion("packettotal"), + utils::packageDescription("packettotal")$URL + ) +) -> .PACKETTOTAL_UA diff --git a/R/api-key.R b/R/api-key.R new file mode 100644 index 0000000..f704025 --- /dev/null +++ b/R/api-key.R @@ -0,0 +1,36 @@ +#' Get or set PACKETTOTAL_API_KEY value +#' +#' The API wrapper functions in this package all rely on a PacketTotal API +#' key residing in the environment variable `PACKETTOTAL_API_KEY`. +#' The easiest way to accomplish this is to set it +#' in the `.Renviron` file in your home directory. +#' +#' @md +#' @param force Force setting a new PacketTotal key for the current environment? +#' @return atomic character vector containing the PacketTotal api key +#' @references +#' @export +packettotal_api_key <- function(force = FALSE) { + + env <- Sys.getenv('PACKETTOTAL_API_KEY') + if (!identical(env, "") && !force) return(env) + + if (!interactive()) { + stop("Please set env var PACKETTOTAL_API_KEY to your PacketTotal key", + call. = FALSE) + } + + message("Couldn't find env var PACKETTOTAL_API_KEY See ?packettotal_api_key for more details.") + message("Please enter your API key:") + pat <- readline(": ") + + if (identical(pat, "")) { + stop("PacketTotal key entry failed", call. = FALSE) + } + + message("Updating PACKETTOTAL_API_KEY env var") + Sys.setenv(PACKETTOTAL_API_KEY = pat) + + pat + +} diff --git a/R/detail.R b/R/detail.R new file mode 100644 index 0000000..ead4820 --- /dev/null +++ b/R/detail.R @@ -0,0 +1,30 @@ +#' Get a detailed report of PCAP traffic, carved files, signatures, and top-talkers. +#' +#' Analysis results contain high-level protocol statistics, signatures, and intelligence that PacketTotal discovered during analysis and enrichment. +#' +#' @param pcap_id An md5 hash corresponding to the PCAP file submission on PacketTotal.com. +#' This hash can be derived by hashing the PCAP file in question. +#' @param api_key your [packettotal_api_key()]. +#' @references +#' @export +#' @examples +#' str(try(pt_detail("d210f4dbea97949f694e849507951881"), silent=TRUE), 2) +pt_detail <- function(pcap_id, api_key = packettotal_api_key()) { + + httr::GET( + url = sprintf("https://api.packettotal.com/v1/pcaps/%s/analysis", pcap_id), + httr::add_headers( + `x-api-key` = api_key + ), + .PACKETTOTAL_UA + ) -> res + + httr::stop_for_status(res) + + out <- httr::content(res, as = "text", encoding = "UTF-8") + + out <- jsonlite::fromJSON(out) + + out + +} \ No newline at end of file diff --git a/R/download.R b/R/download.R new file mode 100644 index 0000000..88b7127 --- /dev/null +++ b/R/download.R @@ -0,0 +1,55 @@ +#' Download a PCAP analysis archive. The result is a zip archive containing the PCAP itself, CSVs representing various analysis results, and all carved files.' +#' +#' @param pcap_id An md5 hash corresponding to the PCAP file submission on PacketTotal.com. +#' This hash can be derived by hashing the PCAP file in question. +#' @param dl_dir directory where to store the download +#' @param archive_name name of the ZIP file. If left `NULL` then a ZIP file +#' will be created with the name `YYYY-mm-dd-pcap_id.zip`. +#' @param api_key your [packettotal_api_key()]. +#' @return if successful and the analysis package is ready then the full path +#' to the ZIP file is returned (invisibly). If the analysis package +#' is not ready the return value is "`_PROCESSING_`". +#' @references +#' @export +#' @examples +#' str(try(pt_download("536cf06ca83704844d789f56caf22ee6"), silent=TRUE), 2) +pt_download <- function(pcap_id, dl_dir = getwd(), archive_name = NULL, + api_key = packettotal_api_key()) { + + dl_dir <- path.expand(dl_dir) + stopifnot(dir.exists(dl_dir)) + + httr::GET( + url = sprintf("https://api.packettotal.com/v1/pcaps/%s/download", pcap_id), + httr::add_headers( + `x-api-key` = api_key + ), + .PACKETTOTAL_UA + ) -> res + + httr::stop_for_status(res) + + status_code <- httr::status_code(res) + + if (status_code == "200") { + out <- httr::content(res, as = "raw", encoding = "UTF-8") + if (is.null(archive_name)) { + loc <- file.path(dl_dir, sprintf("%s-%s.zip", as.character(Sys.Date()), pcap_id)) + } else { + loc <- file.path(dl_dir, archive_name) + } + writeBin( + object = out, + con = loc, + useBytes = TRUE + ) + message("Download is at ", loc) + return(invisible(loc)) + } else { + message( + "PCAP exists but the analysis package is not ready. ", + "Try calling the function again in a few minutes." + ) + } + +} \ No newline at end of file diff --git a/R/graph.R b/R/graph.R new file mode 100644 index 0000000..85b8ea9 --- /dev/null +++ b/R/graph.R @@ -0,0 +1,46 @@ +#' Get a similarity graph relative to the current PCAP file. +#' +#' Results contain PCAPs that exhibit similar behaviors or contain similar content. Results are organized with the most similar PCAPs on top, and the terms that were found shared within both. +#' +#' @param pcap_id An md5 hash corresponding to the PCAP file submission on PacketTotal.com. +#' This hash can be derived by hashing the PCAP file in question. +#' @param weighting_mode One of "`behavior`" (default) or "`content`". Weight search results either based on their similarity to the behaviors exhibited or contents contained within the current PCAP file. +#' @param intensity One of "`minimal`" (default), "`low`", "`medium`", or "`high`". The scope of the search, basically translates to the maximum number of aggregations to exhaust. Using a high level intensity, may result in occassional timeouts. +#' @param prioritize_uncommon_fields By default, the most common values are used to seed the initial similarity search. Enabling this parameter, seeds the initial search with the least common values instead. +#' @param api_key your [packettotal_api_key()]. +#' @references +#' @export +#' @examples +#' str(try(pt_similar("536cf06ca83704844d789f56caf22ee6"), silent=TRUE), 3) +pt_similar <- function(pcap_id, + weighting_mode = c("behavior", "content"), + intensity = c("minimal", "low", "medium", "high"), + prioritize_uncommon_fields = FALSE, + api_key = packettotal_api_key()) { + + weighting_mode <- match.arg(tolower(weighting_mode), c("behavior", "content")) + intensity <- match.arg(tolower(intensity), c("minimal", "low", "medium", "high")) + prioritize_uncommon_fields <- tolower(as.character(FALSE)) + + httr::GET( + url = sprintf("https://api.packettotal.com/v1/pcaps/%s/similar", pcap_id), + query = list( + weighting_mode = weighting_mode, + intensity = intensity, + prioritize_uncommon_fields = prioritize_uncommon_fields + ), + httr::add_headers( + `x-api-key` = api_key + ), + .PACKETTOTAL_UA + ) -> res + + httr::stop_for_status(res) + + out <- httr::content(res, as = "text", encoding = "UTF-8") + + out <- jsonlite::fromJSON(out) + + out + +} \ No newline at end of file diff --git a/R/info.R b/R/info.R new file mode 100644 index 0000000..614d710 --- /dev/null +++ b/R/info.R @@ -0,0 +1,30 @@ +#' Get high-level information about a specific PCAP file. +#' +#' Results will contain high-level information, such as what logs were extracted, the date it was analyzed, and additional references. +#' +#' @param pcap_id An md5 hash corresponding to the PCAP file submission on PacketTotal.com. +#' This hash can be derived by hashing the PCAP file in question. +#' @param api_key your [packettotal_api_key()]. +#' @references +#' @export +#' @examples +#' str(try(pt_info("d210f4dbea97949f694e849507951881"), silent=TRUE), 2) +pt_info <- function(pcap_id, api_key = packettotal_api_key()) { + + httr::GET( + url = sprintf("https://api.packettotal.com/v1/pcaps/%s", pcap_id), + httr::add_headers( + `x-api-key` = api_key + ), + .PACKETTOTAL_UA + ) -> res + + httr::stop_for_status(res) + + out <- httr::content(res, as = "text", encoding = "UTF-8") + + out <- jsonlite::fromJSON(out) + + out + +} \ No newline at end of file diff --git a/R/packettotal-package.R b/R/packettotal-package.R index ae1837c..645a46b 100644 --- a/R/packettotal-package.R +++ b/R/packettotal-package.R @@ -1,12 +1,21 @@ -#' ... -#' +#' Lookup and Analyze Packet Capture ('PCAP') Files +#' +#' 'PacketTotal' () is an engine for analyzing, +#' categorizing, and sharing packet capture ('PCAP') files. The tool was built +#' with the information security community in mind and has applications in malware +#' analysis and network forensics. Methods are provided to query search for and +#' analyze packet capture files. +#' #' - URL: #' - BugReports: -#' +#' #' @md #' @name packettotal #' @docType package #' @author Bob Rudis (bob@@rud.is) +#' @references - +#' - +#' @keywords internal #' @import httr #' @importFrom jsonlite fromJSON NULL diff --git a/R/random.R b/R/random.R new file mode 100644 index 0000000..ac538de --- /dev/null +++ b/R/random.R @@ -0,0 +1,28 @@ +#' Get high-level information about a random PCAP file. +#' +#' Randomly selected PCAPs come from a set of pre-selected, interesting PCAP files. +#' +#' @param api_key your [packettotal_api_key()]. +#' @references +#' @export +#' @examples +#' str(try(pt_random(), silent=TRUE), 1) +pt_random <- function(api_key = packettotal_api_key()) { + + httr::GET( + url = "https://api.packettotal.com/v1/pcaps", + httr::add_headers( + `x-api-key` = api_key + ), + .PACKETTOTAL_UA + ) -> res + + httr::stop_for_status(res) + + out <- httr::content(res, as = "text", encoding = "UTF-8") + + out <- jsonlite::fromJSON(out) + + out + +} \ No newline at end of file diff --git a/R/search.R b/R/search.R new file mode 100644 index 0000000..271bfbb --- /dev/null +++ b/R/search.R @@ -0,0 +1,32 @@ +#' Search with term or with a valid Lucene query. +#' +#' Receive a set of matches for given query. +#' +#' @param query search term (e.g. an IP address, domain, or file hash) or valid Lucene query +#' @param api_key your [packettotal_api_key()]. +#' @export +#' @references res + + httr::stop_for_status(res) + + out <- httr::content(res, as = "text", encoding = "UTF-8") + + out <- jsonlite::fromJSON(out) + + out + +} \ No newline at end of file diff --git a/R/usage.R b/R/usage.R new file mode 100644 index 0000000..d66f926 --- /dev/null +++ b/R/usage.R @@ -0,0 +1,27 @@ +#' Retrive usage and subscription plan information. +#' +#' Handy helper to determine how many requests you have remaining. +#' +#' @param api_key your [packettotal_api_key()]. +#' @export +#' @examples +#' str(try(pt_usage(), silent=TRUE), 2) +pt_usage <- function(api_key = packettotal_api_key()) { + + httr::GET( + url = "https://api.packettotal.com/v1/usage", + httr::add_headers( + `x-api-key` = api_key + ), + .PACKETTOTAL_UA + ) -> res + + httr::stop_for_status(res) + + out <- httr::content(res, as = "text") + + out <- jsonlite::fromJSON(out, encoding = "UTF-8") + + out + +} \ No newline at end of file diff --git a/README.Rmd b/README.Rmd index 8d255b2..0458987 100644 --- a/README.Rmd +++ b/README.Rmd @@ -4,22 +4,44 @@ editor_options: chunk_output_type: inline --- ```{r pkg-knitr-opts, include=FALSE} -knitr$opts_chunk$set(collapse=TRUE, fig.retina=2, message=FALSE, warning=FALSE) +knitr::opts_chunk$set(collapse=TRUE, fig.retina=2, message=FALSE, warning=FALSE) options(width=120) ``` [![Travis-CI Build Status](https://travis-ci.org/hrbrmstr/packettotal.svg?branch=master)](https://travis-ci.org/hrbrmstr/packettotal) [![Coverage Status](https://codecov.io/gh/hrbrmstr/packettotal/branch/master/graph/badge.svg)](https://codecov.io/gh/hrbrmstr/packettotal) -[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/packettotal)](https://cran.r-project.org/package=packettotal) +[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version/packettotal)](https://cran.r-project.org/package=packettotal) # packettotal +Lookup and Analyze Packet Capture ('PCAP') Files + ## Description +'PacketTotal' () is an engine for analyzing, +categorizing, and sharing packet capture ('PCAP') files. The tool was built +with the information security community in mind and has applications in malware +analysis and network forensics. Methods are provided to query search for and +analyze packet capture files. + +## TODO + +- `/search/deep/` : +- `/search/deep/results/{search_id}` : + ## What's Inside The Tin The following functions are implemented: +- `packettotal_api_key`: Get or set PACKETTOTAL_API_KEY value +- `pt_detail`: Get a detailed report of PCAP traffic, carved files, signatures, and top-talkers. +- `pt_download`: Download a PCAP analysis archive. The result is a zip archive containing the PCAP itself, CSVs representing various analysis results, and all carved files. +- `pt_info`: Get high-level information about a specific PCAP file. +- `pt_random`: Get high-level information about a random PCAP file. +- `pt_search`: Search with term or with a valid Lucene query. +- `pt_similar`: Get a similarity graph relative to the current PCAP file. +- `pt_usage`: Retrive usage and subscription plan information. + ## Installation ```{r install-ex, eval=FALSE} @@ -38,6 +60,26 @@ packageVersion("packettotal") ``` +```{r random} +str(pt_random(), 2) +``` + +```{r search} +str(pt_search("evil.com"), 2) +``` + +```{r info} +str(pt_info("d210f4dbea97949f694e849507951881"), 2) +``` + +```{r detail} +str(pt_detail("d210f4dbea97949f694e849507951881"), 2) +``` + +```{r similar} +str(pt_similar("536cf06ca83704844d789f56caf22ee6"), 2) +``` + ## packettotal Metrics ```{r cloc, echo=FALSE} diff --git a/README.md b/README.md index 6eb10ca..b94e4cf 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,142 @@ + +[![Travis-CI Build +Status](https://travis-ci.org/hrbrmstr/packettotal.svg?branch=master)](https://travis-ci.org/hrbrmstr/packettotal) +[![Coverage +Status](https://codecov.io/gh/hrbrmstr/packettotal/branch/master/graph/badge.svg)](https://codecov.io/gh/hrbrmstr/packettotal) +[![CRAN\_Status\_Badge](https://www.r-pkg.org/badges/version/packettotal)](https://cran.r-project.org/package=packettotal) + # packettotal +Lookup and Analyze Packet Capture (‘PCAP’) Files + +## Description + +‘PacketTotal’ () is an engine for analyzing, +categorizing, and sharing packet capture (‘PCAP’) files. The tool was +built with the information security community in mind and has +applications in malware analysis and network forensics. Methods are +provided to query search for and analyze packet capture files. + +## TODO + + - `/search/deep/` : + + - `/search/deep/results/{search_id}` : + + +## What’s Inside The Tin + +The following functions are implemented: + + - `packettotal_api_key`: Get or set PACKETTOTAL\_API\_KEY value + - `pt_detail`: Get a detailed report of PCAP traffic, carved files, + signatures, and top-talkers. + - `pt_download`: Download a PCAP analysis archive. The result is a zip + archive containing the PCAP itself, CSVs representing various + analysis results, and all carved files. + - `pt_info`: Get high-level information about a specific PCAP file. + - `pt_random`: Get high-level information about a random PCAP file. + - `pt_search`: Search with term or with a valid Lucene query. + - `pt_similar`: Get a similarity graph relative to the current PCAP + file. + - `pt_usage`: Retrive usage and subscription plan information. + +## Installation + +``` r +devtools::install_git("https://gitlab.com/hrbrmstr/packettotal.git") +# or +devtools::install_github("hrbrmstr/packettotal") +``` + +## Usage + +``` r +library(packettotal) + +# current version +packageVersion("packettotal") +## [1] '0.1.0' +``` + +``` r +str(pt_random(), 2) +## List of 1 +## $ pcap_metadata:List of 11 +## ..$ md5 : chr "4be31ddcbfe4af10f0fbcb83681d1b67" +## ..$ name : chr "20130820_c_win6_00012_pc.pcap" +## ..$ byte_size : int 1552408 +## ..$ logs : chr [1:8] "conn" "dns" "weird" "files" ... +## ..$ analyzed_date : chr "2018-10-19 00:50:01" +## ..$ download_link : chr "/pcaps/4be31ddcbfe4af10f0fbcb83681d1b67/download" +## ..$ analysis_link : chr "/pcaps/4be31ddcbfe4af10f0fbcb83681d1b67/analysis" +## ..$ similar_pcaps_link: chr "/pcaps/4be31ddcbfe4af10f0fbcb83681d1b67/similar" +## ..$ pcap_glyph_link : chr "https://s3.amazonaws.com/packettotalpub/files/4be31ddcbfe4af10f0fbcb83681d1b67/pcap-mosaic.png" +## ..$ packettotal_link : chr "https://packettotal.com/app/analysis?id=4be31ddcbfe4af10f0fbcb83681d1b67" +## ..$ message : chr "This PCAP was selected randomly, since no id was specified." +``` + +``` r +str(pt_search("evil.com"), 2) +## List of 2 +## $ result_count: int 5 +## $ results :'data.frame': 5 obs. of 3 variables: +## ..$ id : chr [1:5] "b2a094b1882f52ab8befd3d8ad9d7f9a" "0826bfbd4a68519945b9af594a5a87d7" "385b9a5b3da0d56260f2be329e110795" "8e13e95bc12ad8415c4d8e8d313affac" ... +## ..$ found_in :List of 5 +## ..$ match_score: num [1:5] 49.5 49.3 44.2 31.8 31.6 +``` + +``` r +str(pt_info("d210f4dbea97949f694e849507951881"), 2) +## List of 1 +## $ pcap_metadata:List of 10 +## ..$ md5 : chr "d210f4dbea97949f694e849507951881" +## ..$ name : chr "20180815Emotetinfectipca.pcap" +## ..$ byte_size : int 1583713 +## ..$ logs : chr [1:10] "conn" "x509" "dns" "ssl" ... +## ..$ analyzed_date : chr "2019-01-01 06:40:18" +## ..$ download_link : chr "/pcaps/d210f4dbea97949f694e849507951881/download" +## ..$ analysis_link : chr "/pcaps/d210f4dbea97949f694e849507951881/analysis" +## ..$ similar_pcaps_link: chr "/pcaps/d210f4dbea97949f694e849507951881/similar" +## ..$ pcap_glyph_link : chr "https://s3.amazonaws.com/packettotalpub/files/d210f4dbea97949f694e849507951881/pcap-mosaic.png" +## ..$ packettotal_link : chr "https://packettotal.com/app/analysis?id=d210f4dbea97949f694e849507951881" +``` + +``` r +str(pt_detail("d210f4dbea97949f694e849507951881"), 2) +## List of 1 +## $ analysis_summary:List of 9 +## ..$ top_talkers :List of 2 +## ..$ connection_statistics:List of 9 +## ..$ dns_statistics :List of 2 +## ..$ file_statistics :List of 3 +## ..$ signatures : chr [1:4] "ET POLICY Office Document Download Containing AutoOpen Macro" "ET POLICY PE EXE or DLL Windows file download HTTP" "SURICATA TLS invalid record version" "SURICATA TLS invalid record/traffic" +## ..$ external_references :'data.frame': 7 obs. of 2 variables: +## ..$ malicious_traffic : logi FALSE +## ..$ accuracy : chr "perfect" +## ..$ http_statistics :List of 3 +``` + +``` r +str(pt_similar("536cf06ca83704844d789f56caf22ee6"), 2) +## List of 4 +## $ similar :List of 2 +## ..$ result_count: int 78 +## ..$ results :'data.frame': 78 obs. of 4 variables: +## $ intensity : chr "minimal" +## $ prioritize_uncommon_fields: logi TRUE +## $ weighting_mode : chr "behavior" +``` + +## packettotal Metrics + +| Lang | \# Files | (%) | LoC | (%) | Blank lines | (%) | \# Lines | (%) | +| :--- | -------: | ---: | --: | ---: | ----------: | ---: | -------: | ---: | +| R | 12 | 0.92 | 152 | 0.93 | 52 | 0.68 | 111 | 0.67 | +| Rmd | 1 | 0.08 | 12 | 0.07 | 25 | 0.32 | 55 | 0.33 | + +## 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. diff --git a/man/packettotal.Rd b/man/packettotal.Rd index 8d97f5e..1efb916 100644 --- a/man/packettotal.Rd +++ b/man/packettotal.Rd @@ -4,13 +4,27 @@ \name{packettotal} \alias{packettotal} \alias{packettotal-package} -\title{...} +\title{Lookup and Analyze Packet Capture ('PCAP') Files} \description{ +'PacketTotal' (\url{https://packettotal.com/}) is an engine for analyzing, +categorizing, and sharing packet capture ('PCAP') files. The tool was built +with the information security community in mind and has applications in malware +analysis and network forensics. Methods are provided to query search for and +analyze packet capture files. +} +\details{ \itemize{ \item URL: \url{https://gitlab.com/hrbrmstr/packettotal} \item BugReports: \url{https://gitlab.com/hrbrmstr/packettotal/issues} } } +\references{ +\itemize{ +\item \url{https://packettotal.com/} +\item \url{https://packettotal.com/api-docs/#/} +} +} \author{ Bob Rudis (bob@rud.is) } +\keyword{internal} diff --git a/man/packettotal_api_key.Rd b/man/packettotal_api_key.Rd new file mode 100644 index 0000000..83e0c64 --- /dev/null +++ b/man/packettotal_api_key.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/api-key.R +\name{packettotal_api_key} +\alias{packettotal_api_key} +\title{Get or set PACKETTOTAL_API_KEY value} +\usage{ +packettotal_api_key(force = FALSE) +} +\arguments{ +\item{force}{Force setting a new PacketTotal key for the current environment?} +} +\value{ +atomic character vector containing the PacketTotal api key +} +\description{ +The API wrapper functions in this package all rely on a PacketTotal API +key residing in the environment variable \code{PACKETTOTAL_API_KEY}. +The easiest way to accomplish this is to set it +in the \code{.Renviron} file in your home directory. +} +\references{ +\url{https://packettotal.com/api-docs/} +} diff --git a/man/pt_detail.Rd b/man/pt_detail.Rd new file mode 100644 index 0000000..bc95cfa --- /dev/null +++ b/man/pt_detail.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/detail.R +\name{pt_detail} +\alias{pt_detail} +\title{Get a detailed report of PCAP traffic, carved files, signatures, and top-talkers.} +\usage{ +pt_detail(pcap_id, api_key = packettotal_api_key()) +} +\arguments{ +\item{pcap_id}{An md5 hash corresponding to the PCAP file submission on PacketTotal.com. +This hash can be derived by hashing the PCAP file in question.} + +\item{api_key}{your \code{\link[=packettotal_api_key]{packettotal_api_key()}}.} +} +\description{ +Analysis results contain high-level protocol statistics, signatures, and intelligence that PacketTotal discovered during analysis and enrichment. +} +\examples{ +str(try(pt_detail("d210f4dbea97949f694e849507951881"), silent=TRUE), 2) +} +\references{ +\url{https://packettotal.com/api-docs/#/pcaps/get_pcaps} +} diff --git a/man/pt_download.Rd b/man/pt_download.Rd new file mode 100644 index 0000000..d024b75 --- /dev/null +++ b/man/pt_download.Rd @@ -0,0 +1,34 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/download.R +\name{pt_download} +\alias{pt_download} +\title{Download a PCAP analysis archive. The result is a zip archive containing the PCAP itself, CSVs representing various analysis results, and all carved files.'} +\usage{ +pt_download(pcap_id, dl_dir = getwd(), archive_name = NULL, + api_key = packettotal_api_key()) +} +\arguments{ +\item{pcap_id}{An md5 hash corresponding to the PCAP file submission on PacketTotal.com. +This hash can be derived by hashing the PCAP file in question.} + +\item{dl_dir}{directory where to store the download} + +\item{archive_name}{name of the ZIP file. If left \code{NULL} then a ZIP file +will be created with the name \code{YYYY-mm-dd-pcap_id.zip}.} + +\item{api_key}{your \code{\link[=packettotal_api_key]{packettotal_api_key()}}.} +} +\value{ +if successful and the analysis package is ready then the full path +to the ZIP file is returned (invisibly). If the analysis package +is not ready the return value is "\code{_PROCESSING_}". +} +\description{ +Download a PCAP analysis archive. The result is a zip archive containing the PCAP itself, CSVs representing various analysis results, and all carved files.' +} +\examples{ +str(try(pt_download("536cf06ca83704844d789f56caf22ee6"), silent=TRUE), 2) +} +\references{ +\url{https://packettotal.com/api-docs/#/pcaps/get_pcaps__pcap_id__download} +} diff --git a/man/pt_info.Rd b/man/pt_info.Rd new file mode 100644 index 0000000..465cfc3 --- /dev/null +++ b/man/pt_info.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/info.R +\name{pt_info} +\alias{pt_info} +\title{Get high-level information about a specific PCAP file.} +\usage{ +pt_info(pcap_id, api_key = packettotal_api_key()) +} +\arguments{ +\item{pcap_id}{An md5 hash corresponding to the PCAP file submission on PacketTotal.com. +This hash can be derived by hashing the PCAP file in question.} + +\item{api_key}{your \code{\link[=packettotal_api_key]{packettotal_api_key()}}.} +} +\description{ +Results will contain high-level information, such as what logs were extracted, the date it was analyzed, and additional references. +} +\examples{ +str(try(pt_info("d210f4dbea97949f694e849507951881"), silent=TRUE), 2) +} +\references{ +\url{https://packettotal.com/api-docs/#/pcaps/get_pcaps} +} diff --git a/man/pt_random.Rd b/man/pt_random.Rd new file mode 100644 index 0000000..cd7a5a1 --- /dev/null +++ b/man/pt_random.Rd @@ -0,0 +1,20 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/random.R +\name{pt_random} +\alias{pt_random} +\title{Get high-level information about a random PCAP file.} +\usage{ +pt_random(api_key = packettotal_api_key()) +} +\arguments{ +\item{api_key}{your \code{\link[=packettotal_api_key]{packettotal_api_key()}}.} +} +\description{ +Randomly selected PCAPs come from a set of pre-selected, interesting PCAP files. +} +\examples{ +str(try(pt_random(), silent=TRUE), 1) +} +\references{ +\url{https://packettotal.com/api-docs/#/pcaps/get_pcaps} +} diff --git a/man/pt_search.Rd b/man/pt_search.Rd new file mode 100644 index 0000000..23226b4 --- /dev/null +++ b/man/pt_search.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/search.R +\name{pt_search} +\alias{pt_search} +\title{Search with term or with a valid Lucene query.} +\usage{ +pt_search(query, api_key = packettotal_api_key()) +} +\arguments{ +\item{query}{search term (e.g. an IP address, domain, or file hash) or valid Lucene query} + +\item{api_key}{your \code{\link[=packettotal_api_key]{packettotal_api_key()}}.} +} +\description{ +Receive a set of matches for given query. +} +\examples{ +str(try(pt_search("evil.com"), silent=TRUE), 1) +} +\references{ +