initial commit

.Rbuildignore

@@ -1,2 +1,7 @@
 ^.*\.Rproj$
 ^\.Rproj\.user$
+^README\.Rmd$
+^README-.*\.png$
+^\.travis\.yml$
+^CONDUCT\.md$
+^README\.md$

.travis.yml

@@ -0,0 +1,5 @@
+# R for travis: see documentation at https://docs.travis-ci.com/user/languages/r
+
+language: R
+sudo: false
+cache: packages

CONDUCT.md

@@ -0,0 +1,25 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who 
+contribute through reporting issues, posting feature requests, updating documentation,
+submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for
+everyone, regardless of level of experience, gender, gender identity and expression,
+sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or
+imagery, derogatory comments or personal attacks, trolling, public or private harassment,
+insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments,
+commits, code, wiki edits, issues, and other contributions that are not aligned to this 
+Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed 
+from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by 
+opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the Contributor Covenant 
+(http:contributor-covenant.org), version 1.0.0, available at 
+http://contributor-covenant.org/version/1/0/0/

DESCRIPTION

@@ -1,9 +1,17 @@
 Package: ssllabs
-Title: What the Package Does (one line, title case)
+Title: Tools to Work with the `SSL Labs` `API`
-Version: 0.0.0.9000
+Version: 0.1.0.9000
 Authors@R: c(person("Bob", "Rudis", email = "bob@rudis.net", role = c("aut", "cre")))
-Description: What the package does (one paragraph).
+Description: Tools to Work with the `SSL Labs` `API`.
-Depends: R (>= 3.3.0)
+Depends:
+    R (>= 3.0.0)
 License: AGPL + file LICENSE
 Encoding: UTF-8
 LazyData: true
+Suggests:
+    testthat
+Imports:
+    httr,
+    jsonlite,
+    openssl
+RoxygenNote: 5.0.1

NAMESPACE

@@ -1,2 +1,10 @@
-# Generated by roxygen2: fake comment so roxygen2 overwrites silently.
+# Generated by roxygen2: do not edit by hand
-exportPattern("^[^\\.]")
+
+export(analyze_site)
+export(get_endpoint_data)
+export(get_root_certs_raw)
+export(get_status_codes)
+export(ssllabs_api_info)
+import(httr)
+import(jsonlite)
+import(openssl)

R/analyze.r

@@ -0,0 +1,51 @@
+#' Invoke assessment and check progress
+#'
+#' This call is used to initiate an assessment, or to retrieve the status of an assessment
+#' in progress or in the cache. It will return a single Host object on success. The
+#' Endpoint object embedded in the Host object will provide partial endpoint results.
+#' Please note that assessments of individual endpoints can fail even when the overall
+#' assessment is successful (e.g., one server might be down). At this time, you can
+#' determine the success of an endpoint assessment by checking the statusMessage field;
+#' it should contain "Ready".
+#'
+#' @param host hostname; required.
+#' @param publish set to "on" if assessment results should be published on the public
+#'                results boards; optional, defaults to "off".
+#' @param start_new if set to "on" then cached assessment results are ignored and a
+#'                  new assessment is started. However, if there's already an assessment
+#'                  in progress, its status is delivered instead. This parameter should
+#'                  be used only once to initiate a new assessment; further invocations
+#'                  should omit it to avoid causing an assessment loop.
+#' @param from_cache always deliver cached assessment reports if available; optional,
+#'                   defaults to "off". This parameter is intended for API consumers that
+#'                   don't want to wait for assessment results. Can't be used at the same
+#'                   time as the start_new parameter.
+#' @param max_age maximum report age, in hours, if retrieving from cache (from_cache
+#'                parameter set).
+#' @param all by default this call results only summaries of individual endpoints. If this
+#'            parameter is set to "on", full information will be returned. If set to
+#'            "done", full information will be returned only if the assessment is complete
+#'            (status is READY or ERROR).
+#' @param ignore_mismatch set to "on" to proceed with assessments even when the server
+#'                        certificate doesn't match the assessment hostname. Set to off
+#'                        by default. Please note that this parameter is ignored if a
+#'                        cached report is returned.
+#' @references \url{https://github.com/ssllabs/ssllabs-scan/blob/stable/ssllabs-api-docs.md}
+#' @export
+analyze_site <- function(host, publish="off", start_new=NULL,
+                         from_cache="off", max_age=NULL,
+                         all="on", ignore_mismatch="off") {
+
+  res <- httr::GET("https://api.ssllabs.com/api/v2/analyze",
+                   query=list(host=host,
+                              publish=publish,
+                              startNew=start_new,
+                              fromCache=from_cache,
+                              maxAge=max_age,
+                              all=all,
+                              ignoreMismatch=ignore_mismatch))
+
+  dat <- httr::content(res, as="text")
+  jsonlite::fromJSON(dat, flatten=TRUE)
+
+}

R/api-info.r

@@ -0,0 +1,15 @@
+#' Check SSL Labs availability
+#'
+#' This call should be used to check the availability of the SSL Labs servers, retrieve
+#' the engine and criteria version, and initialize the maximum number of concurrent
+#' assessments. Returns one Info object on success.
+#'
+#' @references \url{https://github.com/ssllabs/ssllabs-scan/blob/stable/ssllabs-api-docs.md}
+#' @export
+ssllabs_api_info <- function() {
+
+  res <- httr::GET("https://api.ssllabs.com/api/v2/info")
+  dat <- httr::content(res, as="text")
+  jsonlite::fromJSON(dat, flatten=TRUE)
+
+}

R/endpoint.r

@@ -0,0 +1,26 @@
+#' Retrieve detailed endpoint information
+#'
+#' This call is used to retrieve detailed endpoint information. It will return a single
+#' Endpoint object on success. The object will contain complete assessment information.
+#' This API call does not initiate new assessments, even when a cached report is not
+#' found.
+#'
+#' @param host hostname; required.
+#' @param ip endpoint IP address
+#' @param from_cache always deliver cached assessment reports if available; optional,
+#'                   defaults to "off". This parameter is intended for API consumers that
+#'                   don't want to wait for assessment results. Can't be used at the same
+#'                   time as the start_new parameter.
+#' @references \url{https://github.com/ssllabs/ssllabs-scan/blob/stable/ssllabs-api-docs.md}
+#' @export
+get_endpoint_data <- function(host, ip, from_cache="off") {
+
+  res <- httr::GET("https://api.ssllabs.com/api/v2/getEndpointData",
+                   query=list(host=host,
+                              s=ip,
+                              fromCache=from_cache))
+
+  dat <- httr::content(res, as="text")
+  jsonlite::fromJSON(dat, flatten=TRUE)
+
+}

R/root.r

@@ -0,0 +1,13 @@
+#' Retrieve root certificates
+#'
+#' This call returns the root certificates used for trust validation.
+#'
+#' @references \url{https://github.com/ssllabs/ssllabs-scan/blob/stable/ssllabs-api-docs.md}
+#' @export
+get_root_certs_raw <- function() {
+
+  res <- httr::GET("https://api.ssllabs.com/api/v2/getRootCertsRaw")
+  dat <- httr::content(res, as="text")
+  openssl::read_cert(dat)
+
+}

R/ssllabs-package.r

@@ -0,0 +1,49 @@
+#' Tools to Work with the `SSL Labs` `API`
+#'
+#' SSL Labs APIs are provided free of charge, subject to our terms and conditions:
+#' \url{https://www.ssllabs.com/about/terms.html}. The spirit of the license is that the
+#' APIs are made available so that system operators can test their own infrastructure.
+#' Please read the actual terms and conditions, which are more involved and cover things
+#' such as integrating with open source projects, and so on. For example, it's important
+#' (for reasons of privacy, compliance, etc.) for end users to understand that assessments
+#' are carried out by Qualys's servers, not locally.
+#'
+#' Commercial use is generally not allowed, except with an explicit permission from Qualys.
+#' That said, we're usually happy to support good causes, even uses by commercial
+#' organizations that help improve the security of their customers. If you're a CA, CDN,
+#' hosting company, domain name registrar, we're happy for you to use our APIs (but you
+#' still have to get in touch with us before you begin).
+#'
+#' Please note the following:
+#'
+#' Server assessments usually take at least 60 seconds. (They are intentionally slow, to
+#' avoid harming servers.) Thus, there is no need to poll for the results very often. In
+#' fact, polling too often slows down the service for everyone. It's best to use variable
+#' polling: 5 seconds until an assessment gets under way (status changes to IN_PROGRESS),
+#' then 10 seconds until it completes.
+#'
+#' Keep down the number of concurrent assessments to a minimum. If you're not in a hurry,
+#' test only one hostname at a time.
+#'
+#' SSL Labs may limit your usage of the API, by enforcing a limit on concurrent
+#' assessments, and the overall number of assessments performed in a time period. If that
+#' happens, we will respond with 429 (Too Many Requests) to API calls that wish to
+#' initiate new assessments. Your ability to follow previously initiated assessments, or
+#' retrieve assessment results from the cache, will not be impacted. If you receive a 429
+#' response, reduce the number of concurrent assessments and check that you're not
+#' submitting new assessments at a rate higher than allowed.
+#'
+#' If the server is overloaded (a condition that is not a result of the client's
+#' behaviour), the 529 status code will be used instead. This is not a situation we wish
+#' to be in. If you encounter it, take a break and come back later.
+#'
+#' All successful API calls contain response headers X-Max-Assessments and
+#' X-Current-Assessments. They can be used to calculate how many new assessments can be
+#' submitted. It is recommended that clients update their internal state after each
+#' complete response.
+#'
+#' @name ssllabs
+#' @docType package
+#' @author Bob Rudis (@@hrbrmstr)
+#' @import httr jsonlite openssl
+NULL

R/status.r

@@ -0,0 +1,13 @@
+#' Retrieve known status codes
+#'
+#' This call will return one StatusCodes instance.
+#'
+#' @references \url{https://github.com/ssllabs/ssllabs-scan/blob/stable/ssllabs-api-docs.md}
+#' @export
+get_status_codes <- function() {
+
+  res <- httr::GET("https://api.ssllabs.com/api/v2/getStatusCodes")
+  dat <- httr::content(res, as="text")
+  jsonlite::fromJSON(dat, flatten=TRUE)
+
+}

README.Rmd

@@ -0,0 +1,64 @@
+---
+output: github_document
+---
+
+<!-- README.md is generated from README.Rmd. Please edit that file -->
+
+```{r, echo = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>",
+  fig.path = "README-"
+)
+```
+
+[![Build Status](https://travis-ci.org/hrbrmstr/ssllabs.svg)](https://travis-ci.org/hrbrmstr/ssllabs) 
+![Project Status: Concept - Minimal or no implementation has been done yet.](http://www.repostatus.org/badges/0.1.0/concept.svg)](http://www.repostatus.org/#concept)
+[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/ssllabs)](http://cran.r-project.org/web/packages/ssllabs) 
+![downloads](http://cranlogs.r-pkg.org/badges/grand-total/ssllabs)
+
+ssllabs is ...
+
+The following functions are implemented:
+
+The following data sets are included:
+
+### News
+
+- Version  released
+
+### Installation
+
+```{r eval=FALSE}
+devtools::install_github("hrbrmstr/ssllabs")
+```
+
+```{r echo=FALSE, message=FALSE, warning=FALSE, error=FALSE}
+options(width=120)
+```
+
+### Usage
+
+```{r}
+library(ssllabs)
+
+# current verison
+packageVersion("ssllabs")
+
+```
+
+### Test Results
+
+```{r}
+library(ssllabs)
+library(testthat)
+
+date()
+
+test_dir("tests/")
+```
+
+### 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.

README.md

@@ -0,0 +1,65 @@
+---
+output: github_document
+---
+
+<!-- README.md is generated from README.Rmd. Please edit that file -->
+
+
+
+[![Build Status](https://travis-ci.org/hrbrmstr/ssllabs.svg)](https://travis-ci.org/hrbrmstr/ssllabs) 
+![Project Status: Concept - Minimal or no implementation has been done yet.](http://www.repostatus.org/badges/0.1.0/concept.svg)](http://www.repostatus.org/#concept)
+[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/ssllabs)](http://cran.r-project.org/web/packages/ssllabs) 
+![downloads](http://cranlogs.r-pkg.org/badges/grand-total/ssllabs)
+
+ssllabs is ...
+
+The following functions are implemented:
+
+The following data sets are included:
+
+### News
+
+- Version  released
+
+### Installation
+
+
+```r
+devtools::install_github("hrbrmstr/ssllabs")
+```
+
+
+
+### Usage
+
+
+```r
+library(ssllabs)
+#> Error in library(ssllabs): there is no package called 'ssllabs'
+
+# current verison
+packageVersion("ssllabs")
+#> Error in packageVersion("ssllabs"): package 'ssllabs' not found
+```
+
+### Test Results
+
+
+```r
+library(ssllabs)
+#> Error in library(ssllabs): there is no package called 'ssllabs'
+library(testthat)
+
+date()
+#> [1] "Sat Jun  4 22:42:29 2016"
+
+test_dir("tests/")
+#> Error in library(ssllabs): there is no package called 'ssllabs'
+#> 
+#> DONE ===================================================================================================================
+```
+
+### 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.

man/analyze_site.Rd

@@ -0,0 +1,52 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/analyze.r
+\name{analyze_site}
+\alias{analyze_site}
+\title{Invoke assessment and check progress}
+\usage{
+analyze_site(host, publish = "off", start_new = NULL, from_cache = "off",
+  max_age = NULL, all = "on", ignore_mismatch = "off")
+}
+\arguments{
+\item{host}{hostname; required.}
+
+\item{publish}{set to "on" if assessment results should be published on the public
+results boards; optional, defaults to "off".}
+
+\item{start_new}{if set to "on" then cached assessment results are ignored and a
+new assessment is started. However, if there's already an assessment
+in progress, its status is delivered instead. This parameter should
+be used only once to initiate a new assessment; further invocations
+should omit it to avoid causing an assessment loop.}
+
+\item{from_cache}{always deliver cached assessment reports if available; optional,
+defaults to "off". This parameter is intended for API consumers that
+don't want to wait for assessment results. Can't be used at the same
+time as the start_new parameter.}
+
+\item{max_age}{maximum report age, in hours, if retrieving from cache (from_cache
+parameter set).}
+
+\item{all}{by default this call results only summaries of individual endpoints. If this
+parameter is set to "on", full information will be returned. If set to
+"done", full information will be returned only if the assessment is complete
+(status is READY or ERROR).}
+
+\item{ignore_mismatch}{set to "on" to proceed with assessments even when the server
+certificate doesn't match the assessment hostname. Set to off
+by default. Please note that this parameter is ignored if a
+cached report is returned.}
+}
+\description{
+This call is used to initiate an assessment, or to retrieve the status of an assessment
+in progress or in the cache. It will return a single Host object on success. The
+Endpoint object embedded in the Host object will provide partial endpoint results.
+Please note that assessments of individual endpoints can fail even when the overall
+assessment is successful (e.g., one server might be down). At this time, you can
+determine the success of an endpoint assessment by checking the statusMessage field;
+it should contain "Ready".
+}
+\references{
+\url{https://github.com/ssllabs/ssllabs-scan/blob/stable/ssllabs-api-docs.md}
+}
+

man/get_endpoint_data.Rd

@@ -0,0 +1,28 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/endpoint.r
+\name{get_endpoint_data}
+\alias{get_endpoint_data}
+\title{Retrieve detailed endpoint information}
+\usage{
+get_endpoint_data(host, ip, from_cache = "off")
+}
+\arguments{
+\item{host}{hostname; required.}
+
+\item{ip}{endpoint IP address}
+
+\item{from_cache}{always deliver cached assessment reports if available; optional,
+defaults to "off". This parameter is intended for API consumers that
+don't want to wait for assessment results. Can't be used at the same
+time as the start_new parameter.}
+}
+\description{
+This call is used to retrieve detailed endpoint information. It will return a single
+Endpoint object on success. The object will contain complete assessment information.
+This API call does not initiate new assessments, even when a cached report is not
+found.
+}
+\references{
+\url{https://github.com/ssllabs/ssllabs-scan/blob/stable/ssllabs-api-docs.md}
+}
+

man/get_root_certs_raw.Rd

@@ -0,0 +1,15 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/root.r
+\name{get_root_certs_raw}
+\alias{get_root_certs_raw}
+\title{Retrieve root certificates}
+\usage{
+get_root_certs_raw()
+}
+\description{
+This call returns the root certificates used for trust validation.
+}
+\references{
+\url{https://github.com/ssllabs/ssllabs-scan/blob/stable/ssllabs-api-docs.md}
+}
+

man/get_status_codes.Rd

@@ -0,0 +1,15 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/status.r
+\name{get_status_codes}
+\alias{get_status_codes}
+\title{Retrieve known status codes}
+\usage{
+get_status_codes()
+}
+\description{
+This call will return one StatusCodes instance.
+}
+\references{
+\url{https://github.com/ssllabs/ssllabs-scan/blob/stable/ssllabs-api-docs.md}
+}
+

man/ssllabs.Rd

@@ -0,0 +1,55 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/ssllabs-package.r
+\docType{package}
+\name{ssllabs}
+\alias{ssllabs}
+\alias{ssllabs-package}
+\title{Tools to Work with the `SSL Labs` `API`}
+\description{
+SSL Labs APIs are provided free of charge, subject to our terms and conditions:
+\url{https://www.ssllabs.com/about/terms.html}. The spirit of the license is that the
+APIs are made available so that system operators can test their own infrastructure.
+Please read the actual terms and conditions, which are more involved and cover things
+such as integrating with open source projects, and so on. For example, it's important
+(for reasons of privacy, compliance, etc.) for end users to understand that assessments
+are carried out by Qualys's servers, not locally.
+}
+\details{
+Commercial use is generally not allowed, except with an explicit permission from Qualys.
+That said, we're usually happy to support good causes, even uses by commercial
+organizations that help improve the security of their customers. If you're a CA, CDN,
+hosting company, domain name registrar, we're happy for you to use our APIs (but you
+still have to get in touch with us before you begin).
+
+Please note the following:
+
+Server assessments usually take at least 60 seconds. (They are intentionally slow, to
+avoid harming servers.) Thus, there is no need to poll for the results very often. In
+fact, polling too often slows down the service for everyone. It's best to use variable
+polling: 5 seconds until an assessment gets under way (status changes to IN_PROGRESS),
+then 10 seconds until it completes.
+
+Keep down the number of concurrent assessments to a minimum. If you're not in a hurry,
+test only one hostname at a time.
+
+SSL Labs may limit your usage of the API, by enforcing a limit on concurrent
+assessments, and the overall number of assessments performed in a time period. If that
+happens, we will respond with 429 (Too Many Requests) to API calls that wish to
+initiate new assessments. Your ability to follow previously initiated assessments, or
+retrieve assessment results from the cache, will not be impacted. If you receive a 429
+response, reduce the number of concurrent assessments and check that you're not
+submitting new assessments at a rate higher than allowed.
+
+If the server is overloaded (a condition that is not a result of the client's
+behaviour), the 529 status code will be used instead. This is not a situation we wish
+to be in. If you encounter it, take a break and come back later.
+
+All successful API calls contain response headers X-Max-Assessments and
+X-Current-Assessments. They can be used to calculate how many new assessments can be
+submitted. It is recommended that clients update their internal state after each
+complete response.
+}
+\author{
+Bob Rudis (@hrbrmstr)
+}
+

man/ssllabs_api_info.Rd

@@ -0,0 +1,17 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/api-info.r
+\name{ssllabs_api_info}
+\alias{ssllabs_api_info}
+\title{Check SSL Labs availability}
+\usage{
+ssllabs_api_info()
+}
+\description{
+This call should be used to check the availability of the SSL Labs servers, retrieve
+the engine and criteria version, and initialize the maximum number of concurrent
+assessments. Returns one Info object on success.
+}
+\references{
+\url{https://github.com/ssllabs/ssllabs-scan/blob/stable/ssllabs-api-docs.md}
+}
+

ssllabs.Rproj

@@ -14,3 +14,12 @@ BuildType: Package
 PackageUseDevtools: Yes
 PackageInstallArgs: --no-multiarch --with-keep.source
 PackageRoxygenize: rd,collate,namespace
+
+UseSpacesForTab: Yes
+NumSpacesForTab: 2
+
+RnwWeave: Sweave
+LaTeX: pdfLaTeX
+
+PackageBuildArgs: --resave-data
+PackageCheckArgs: --as-cran

tests/testthat.R

@@ -0,0 +1,4 @@
+library(testthat)
+library(ssllabs)
+
+test_check("ssllabs")

tests/testthat/test-ssllabs.R

@@ -0,0 +1,6 @@
+context("basic functionality")
+test_that("we can do something", {
+
+  #expect_that(some_function(), is_a("data.frame"))
+
+})