Browse Source

API complete

master
boB Rudis 3 years ago
parent
commit
8fe6708917
No known key found for this signature in database GPG Key ID: 1D7529BE14E2BBA9
  1. 2
      NAMESPACE
  2. 73
      R/deep-search.R
  3. 3
      R/search.R
  4. 14
      README.Rmd
  5. 54
      README.md
  6. 28
      man/pt_deep_search.Rd

2
NAMESPACE

@ -1,8 +1,10 @@
# Generated by roxygen2: do not edit by hand
export(packettotal_api_key)
export(pt_deep_search)
export(pt_detail)
export(pt_download)
export(pt_get_search_results)
export(pt_info)
export(pt_random)
export(pt_search)

73
R/deep-search.R

@ -0,0 +1,73 @@
#' Create a new deep search task. Search for a term or with a Lucene query.
#'
#' Unlike the more lighweight [pt_search()] results from this endpoint
#' will be available at the returned URL.
#'
#' @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 <https://packettotal.com/api-docs/#/search
#' @examples
#' str(try(pt_deep_search("botnet OR malware"), silent=TRUE), 1)
pt_deep_search <- function(query, api_key = packettotal_api_key()) {
httr::POST(
url = "https://api.packettotal.com/v1/search/deep",
body = list(
query = query
),
encode = "json",
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)
class(out) <- "pt_search_result"
out
}
#' @rdname pt_deep_search
#' @param search_result output from [pt_deep_search()] or a plain search results id
#' @export
pt_get_search_results <- function(search_result, api_key = packettotal_api_key()) {
res_url <- NULL
if (inherits(search_result, "pt_search_result")) {
res_url <- sprintf("https://api.packettotal.com%s", search_result$results_uri)
} else if (is.character(search_result)) {
search_result <- search_result[1]
if (grepl("v1/", search_result)) {
res_url <- sprintf("https://api.packettotal.com%s", search_result)
} else {
res_url <- sprintf("https://api.packettotal.com/v1/search/deep/results/%s", search_result)
}
}
if (is.null(res_url)) stop("Unrecognized search result.", call.=FALSE)
httr::GET(
url = res_url,
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
}

3
R/search.R

@ -29,4 +29,5 @@ pt_search <- function(query, api_key = packettotal_api_key()) {
out
}
}

14
README.Rmd

@ -1,7 +1,7 @@
---
output: rmarkdown::github_document
editor_options:
chunk_output_type: inline
chunk_output_type: console
---
```{r pkg-knitr-opts, include=FALSE}
knitr::opts_chunk$set(collapse=TRUE, fig.retina=2, message=FALSE, warning=FALSE)
@ -24,16 +24,12 @@ 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/` : <https://packettotal.com/api-docs/#/search/post_search_deep>
- `/search/deep/results/{search_id}` : <https://packettotal.com/api-docs/#/search/get_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_deep_search`/`pt_get_search_results`: Create a new deep search task. Search for a term or with a Lucene query.
- `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.
@ -68,6 +64,12 @@ str(pt_random(), 2)
str(pt_search("evil.com"), 2)
```
```{r deep-search}
(res <- pt_deep_search("botnet OR malware"))
str(pt_get_search_results(res), 2)
```
```{r info}
str(pt_info("d210f4dbea97949f694e849507951881"), 2)
```

54
README.md

@ -17,18 +17,13 @@ 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/` :
<https://packettotal.com/api-docs/#/search/post_search_deep>
- `/search/deep/results/{search_id}` :
<https://packettotal.com/api-docs/#/search/get_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_deep_search`/`pt_get_search_results`: Create a new deep search
task. Search for a term or with a Lucene query.
- `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
@ -63,16 +58,16 @@ packageVersion("packettotal")
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
## ..$ md5 : chr "e205fca1d43f5588afa2ccde979f056a"
## ..$ name : chr "20130820_c_win1_00071_pc.pcap"
## ..$ byte_size : int 1694276
## ..$ 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"
## ..$ analyzed_date : chr "2018-10-19 05:04:42"
## ..$ download_link : chr "/pcaps/e205fca1d43f5588afa2ccde979f056a/download"
## ..$ analysis_link : chr "/pcaps/e205fca1d43f5588afa2ccde979f056a/analysis"
## ..$ similar_pcaps_link: chr "/pcaps/e205fca1d43f5588afa2ccde979f056a/similar"
## ..$ pcap_glyph_link : chr "https://s3.amazonaws.com/packettotalpub/files/e205fca1d43f5588afa2ccde979f056a/pcap-mosaic.png"
## ..$ packettotal_link : chr "https://packettotal.com/app/analysis?id=e205fca1d43f5588afa2ccde979f056a"
## ..$ message : chr "This PCAP was selected randomly, since no id was specified."
```
@ -87,6 +82,29 @@ str(pt_search("evil.com"), 2)
```
``` r
(res <- pt_deep_search("botnet OR malware"))
## $search_id
## [1] "089f9e75d8142e185e84e8668da4b9b8"
##
## $message
## [1] "Deep search exists."
##
## $results_uri
## [1] "/v1/search/deep/results/089f9e75d8142e185e84e8668da4b9b8"
##
## attr(,"class")
## [1] "pt_search_result"
str(pt_get_search_results(res), 2)
## List of 2
## $ results :'data.frame': 1819 obs. of 3 variables:
## ..$ id : chr [1:1819] "bd00b1dca3e5586dccffdc23579b0d39" "ba796317651f2064b1ca193e6e2cf947" "52419b8eba8af8fe502f8be324b67cb8" "da0023e2c4ca40ac480a4fdb930e7745" ...
## ..$ found_in :List of 1819
## ..$ match_score: num [1:1819] 1584 1079 749 704 653 ...
## $ result_count: int 1819
```
``` r
str(pt_info("d210f4dbea97949f694e849507951881"), 2)
## List of 1
## $ pcap_metadata:List of 10
@ -132,8 +150,8 @@ str(pt_similar("536cf06ca83704844d789f56caf22ee6"), 2)
| 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 |
| R | 13 | 0.93 | 200 | 0.93 | 69 | 0.73 | 125 | 0.69 |
| Rmd | 1 | 0.07 | 14 | 0.07 | 25 | 0.27 | 55 | 0.31 |
## Code of Conduct

28
man/pt_deep_search.Rd

@ -0,0 +1,28 @@
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/deep-search.R
\name{pt_deep_search}
\alias{pt_deep_search}
\alias{pt_get_search_results}
\title{Create a new deep search task. Search for a term or with a Lucene query.}
\usage{
pt_deep_search(query, api_key = packettotal_api_key())
pt_get_search_results(search_result, 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()}}.}
\item{search_result}{output from \code{\link[=pt_deep_search]{pt_deep_search()}} or a plain search results id}
}
\description{
Unlike the more lighweight \code{\link[=pt_search]{pt_search()}} results from this endpoint
will be available at the returned URL.
}
\examples{
str(try(pt_deep_search("botnet OR malware"), silent=TRUE), 1)
}
\references{
<https://packettotal.com/api-docs/#/search
}
Loading…
Cancel
Save