[−][src]Crate tenable

This is an API Abstraction for the Tenable API.

The API itself is far too big for one person to develop. That is the reason why this crate does not provide methods for all endpoints, but instead focuses on modularity and extensability. Instead of providing methods for all endpoints, this crate makes it as easy as possible for users to add their own endpoints and hopefully contribute them afterwards.

Usage

Add this crate as a dependency to your Cargo.toml. Afterwards you can use it like this to execute api calls like fetching all assets:

Sync

use std::convert::Infallible;
use reqwest::blocking::Client;
use tenable::{requests::AssetReq, Error, Response, Tenable};
use http::Request;

pub fn request(req: Request<Vec<u8>>) -> Result<Response, Error<reqwest::Error>> {
    let (req, body) = req.into_parts();
    let res = Client::new()
        .request(req.method, &req.uri.to_string())
        .headers(req.headers)
        .body(body)
        .send()
        .map_err(Error::Request)?;
    Ok(Response {
        status: res.status(),
        body: res.bytes().map_err(Error::Request)?,
    })
}

let tenable = Tenable::new(
    "0000000000000000000000000000000000000000000000000000000000000000",
    "0000000000000000000000000000000000000000000000000000000000000000",
);
let req = tenable.assets();
let _assets = Tenable::request(req, request).expect("Unable to list all assets");

Async

use std::convert::Infallible;
use reqwest::Client;
use tenable::{requests::AssetReq, types::Assets, Error, Response, Tenable};
use http::Request;

pub async fn request_async(req: Request<Vec<u8>>) -> Result<Response, Error<reqwest::Error>> {
   let (req, body) = req.into_parts();
   let res = Client::new()
       .request(req.method, &req.uri.to_string())
       .headers(req.headers)
       .body(body)
       .send()
       .await
       .map_err(Error::Request)?;
   Ok(Response {
       status: res.status(),
       body: res.bytes().await.map_err(Error::Request)?,
   })
}

let tenable = Tenable::new(
    "0000000000000000000000000000000000000000000000000000000000000000",
    "0000000000000000000000000000000000000000000000000000000000000000",
);
let req = tenable.assets();
let _assets: Assets = Tenable::request_async(req, request_async).await
    .expect("Unable to list all assets");

Extending

Extending the functionality is possible by creating a type that implements HttpRequest, which defines how a request looks like and how to handle the server response. The following shows how to do that using the AssetsReq type which handles the /assets endpoint:

use http::{header::HeaderValue, status::StatusCode, Method, Request};
use tenable::{
   types::Assets,
   Error, HttpRequest, Response, Tenable,
};
use std::fmt;

#[derive(Clone, Debug)]
pub struct AssetsReq<'a> {
    pub tenable: &'a Tenable<'a>,
}

impl<RE: fmt::Debug> HttpRequest<RE> for AssetsReq<'_> {
    // The final concret type returned on a successful call
    type Output = Assets;

    #[inline]
    fn to_request(&self) -> Result<Request<Vec<u8>>, Error<RE>> {
        // Create a request...
        let req = Request::builder()
            // ...by specificing the endpoint...
            .uri(format!("{}/assets", self.tenable.uri))
            // ...the method...
            .method(Method::GET)
            // ...authorization...
            .header(
                "X-ApiKeys",
                HeaderValue::from_str(self.tenable.auth.as_ref())?,
            )
            // ...and more like required headers, form parameters, body...
            .header("Accept", HeaderValue::from_static("application/json"))
            .body(Vec::new())?;
        Ok(req)
    }

    #[inline]
    fn from_response(&self, res: Response) -> Result<Self::Output, Error<RE>> {
        // Handles the server response
        match res.status {
            // When the call was successfull, continue with deserializing
            StatusCode::OK => Ok(serde_json::from_slice(&res.body)?),
            // Otherwise, check whether the server returned one of the known errors
            StatusCode::FORBIDDEN => Err(Error::InsufficientPermission),
            StatusCode::TOO_MANY_REQUESTS => Err(Error::RateLimitReached),
            // Every other error may be collected in catch all type
            code => Err(Error::UnexpectedStatusCode(code)),
        }
    }
}

To be able to directly use the type with the tenable struct, we can add a new trait and implement it for tenable

use tenable::{Tenable, types::AssetsReq};

pub trait AssetReq {
    fn assets(&self) -> AssetsReq<'_>;
}

impl AssetReq for Tenable<'_> {
    fn assets(&self) -> AssetsReq<'_> {
        AssetsReq { tenable: self }
    }
}

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Modules

requests	Tenable API Endpoints grouped by Type
types	Tenable Types returned or expected by server

Structs

Response	Server Response allowing further processing
Tenable	Tenable Client which allows requests against the tenable API

Enums

Error

Possible error types occuring in this library

Traits

HttpRequest

Generic Requests which provides information for further processing using the HTTP function given by the user