feroxfuzz/observers/

response.rs

use super::{Observer, ObserverHooks};
use crate::actions::Action;
use crate::requests::{Request, RequestId};
use crate::responses::{Response, Timed};
use crate::std_ext::tuple::Named;

use std::collections::HashMap;

use cfg_if::cfg_if;
#[cfg(feature = "serde")]
use serde::{Deserialize, Serialize};
use tracing::instrument;
use url::Url;

const RESPONSE_OBSERVER_NAME: &str = "ResponseObserver";

/// observes the given implementor of implementor of [`Response`] and [`Timed`]
#[derive(Clone, Debug, PartialEq, Eq, Ord, PartialOrd)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct ResponseObserver<R>
where
    R: Response,
{
    // satisfy Named trait
    name: &'static str,
    // satisfy ResponseExt trait
    response: R,
}

impl<R> Timed for ResponseObserver<R>
where
    R: Response + Timed,
{
    fn elapsed(&self) -> &std::time::Duration {
        self.response.elapsed()
    }
}

impl<R> ResponseObserver<R>
where
    R: Response + Default,
{
    /// create a new `ResponseObserver`
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// given an implementor of [`Response`], return a new `ResponseObserver`
    ///
    /// # Examples
    ///
    /// While the example below works, the normal use-case for this struct is to pass
    /// it, and any other [`Observers`] to the [`build_observers`] macro, and pass
    /// the result of that call to your chosen [`Fuzzer`] implementation.
    ///
    /// [`build_observers`]: crate::build_observers
    /// [`Fuzzer`]: crate::fuzzers::Fuzzer
    /// [`Observers`]: crate::observers::Observers
    ///
    /// ```
    /// # use http;
    /// # use feroxfuzz::responses::{Response, AsyncResponse};
    /// # use feroxfuzz::requests::Request;
    /// # use feroxfuzz::prelude::*;
    /// # use feroxfuzz::observers::ResponseObserver;
    /// # use tokio_test;
    /// # use std::time::Duration;
    /// # fn main() -> Result<(), FeroxFuzzError> {
    /// # tokio_test::block_on(async {
    /// // for testing, normal Response comes as a result of a sent request
    /// let reqwest_response = http::response::Builder::new().status(302).header("Location", "/somewhere").body("").unwrap();
    ///
    /// // should come from timing during the client's send function
    /// let elapsed = Duration::from_secs(1);  
    ///
    /// let response = AsyncResponse::try_from_reqwest_response(Request::default(), reqwest_response.into(), elapsed).await?;
    /// let observer = ResponseObserver::with_response(response);
    ///
    /// # Result::<(), FeroxFuzzError>::Ok(())
    /// # })
    /// # }
    /// ```
    pub const fn with_response(response: R) -> Self
    where
        R: Response,
    {
        Self {
            response,
            name: RESPONSE_OBSERVER_NAME,
        }
    }

    /// true if this `Response` is a well-formed HTTP redirect
    ///
    /// i.e. response code is 3XX and has a Location header
    ///
    /// # Examples
    ///
    /// ```
    /// # use http;
    /// # use feroxfuzz::responses::{Response, AsyncResponse};
    /// # use feroxfuzz::requests::Request;
    /// # use feroxfuzz::error::FeroxFuzzError;
    /// # use feroxfuzz::observers::ResponseObserver;
    /// # use tokio_test;
    /// # use std::time::Duration;
    /// # fn main() -> Result<(), FeroxFuzzError> {
    /// # tokio_test::block_on(async {
    /// // for testing, normal Response comes as a result of a sent request
    /// let reqwest_response = http::response::Builder::new().status(302).header("Location", "/somewhere").body("").unwrap();
    ///
    /// // should come from timing during the client's send function
    /// let elapsed = Duration::from_secs(1);  
    ///
    /// let response = AsyncResponse::try_from_reqwest_response(Request::default(), reqwest_response.into(), elapsed).await?;
    /// let observer: ResponseObserver<_> = response.into();
    ///
    /// assert_eq!(observer.is_redirect(), true);
    /// assert_eq!(observer.is_permanent_redirect(), false);
    /// # Result::<(), FeroxFuzzError>::Ok(())
    /// # })
    /// # }
    /// ```
    #[must_use]
    pub fn is_redirect(&self) -> bool {
        let is_redirect = (300..400).contains(&self.status_code());

        is_redirect
            && (self.headers().contains_key("Location") || self.headers().contains_key("location"))
    }

    /// true if this `Response` is one of the permanent versions of redirect
    ///
    /// i.e. response code is 301 (Moved Permanently) or 308 (Permanent Redirect)
    /// and has a Location header
    ///
    /// # Examples
    ///
    /// ```
    /// # use http;
    /// # use feroxfuzz::responses::{Response, AsyncResponse};
    /// # use feroxfuzz::observers::ResponseObserver;
    /// # use feroxfuzz::requests::Request;
    /// # use feroxfuzz::error::FeroxFuzzError;
    /// # use tokio_test;
    /// # use std::time::Duration;
    /// # fn main() -> Result<(), FeroxFuzzError> {
    /// # tokio_test::block_on(async {
    /// // for testing, normal Response comes as a result of a sent request
    /// let reqwest_response = http::response::Builder::new().status(308).header("Location", "/somewhere").body("").unwrap();
    ///
    /// // should come from timing during the client's send function
    /// let elapsed = Duration::from_secs(1);  
    ///
    /// let response = AsyncResponse::try_from_reqwest_response(Request::default(), reqwest_response.into(), elapsed).await?;
    /// let observer: ResponseObserver<_> = response.into();
    ///
    /// assert_eq!(observer.is_redirect(), true);
    /// assert_eq!(observer.is_permanent_redirect(), true);
    /// # Result::<(), FeroxFuzzError>::Ok(())
    /// # })
    /// # }
    /// ```
    #[must_use]
    pub fn is_permanent_redirect(&self) -> bool {
        let numeric_code = self.status_code();
        let is_permanent_redirect = numeric_code == 301 || numeric_code == 308;

        is_permanent_redirect
            && (self.headers().contains_key("Location") || self.headers().contains_key("location"))
    }

    /// determine whether the response is a directory
    ///
    /// handles 2xx and 3xx responses by either checking if the url ends with a / (2xx)
    /// or if the Location header is present and matches the base url + / (3xx)
    ///
    /// # Examples
    ///
    /// example code requires the **crate-feature** `reqwest`
    ///
    /// A 2xx status code, with a path ending in `/` is interpreted as a directory
    ///
    /// ```
    /// # use http;
    /// # use feroxfuzz::responses::{Response, AsyncResponse};
    /// # use feroxfuzz::requests::Request;
    /// # use feroxfuzz::error::FeroxFuzzError;
    /// # use feroxfuzz::observers::ResponseObserver;
    /// # use tokio_test;
    /// # use std::time::Duration;
    /// # fn main() -> Result<(), FeroxFuzzError> {
    /// # tokio_test::block_on(async {
    /// // for testing, normal Response comes as a result of a sent request
    /// let reqwest_response = http::response::Builder::new().status(200).body("derp").unwrap();
    ///
    /// // should come from timing during the client's send function
    /// let elapsed = Duration::from_secs(1);  
    ///
    /// let response = AsyncResponse::try_from_reqwest_response(Request::default(), reqwest_response.into(), elapsed).await?;
    /// let observer: ResponseObserver<_> = response.into();
    ///
    /// assert_eq!(observer.url().as_str(), "http://no.url.provided.local/");
    /// assert_eq!(observer.is_directory(), true);
    /// # Result::<(), FeroxFuzzError>::Ok(())
    /// # })
    /// # }
    /// ```
    ///
    /// A 3xx response with a location header that matches base url + /
    ///
    /// ```
    /// # use http;
    /// # use feroxfuzz::responses::{Response, AsyncResponse};
    /// # use feroxfuzz::observers::ResponseObserver;
    /// # use feroxfuzz::requests::Request;
    /// # use feroxfuzz::error::FeroxFuzzError;
    /// # use tokio_test;
    /// # use std::time::Duration;
    /// # fn main() -> Result<(), FeroxFuzzError> {
    /// # tokio_test::block_on(async {
    /// // for testing, normal Response comes as a result of a sent request
    /// let mut reqwest_response = http::response::Builder::new().status(301).header("Location", "/").body("").unwrap();
    ///
    /// // should come from timing during the client's send function
    /// let elapsed = Duration::from_secs(1);  
    ///
    /// let response = AsyncResponse::try_from_reqwest_response(Request::default(), reqwest_response.into(), elapsed).await?;
    /// let observer: ResponseObserver<_> = response.into();
    ///
    /// assert_eq!(observer.url().as_str(), "http://no.url.provided.local/");
    /// assert_eq!(observer.is_directory(), true);
    /// # Result::<(), FeroxFuzzError>::Ok(())
    /// # })
    /// # }
    /// ```
    pub fn is_directory(&self) -> bool {
        if self.status_code() >= 300 && self.status_code() < 400 {
            // status code is 3xx
            if let Some(location) = self.get_header_case_insensitive("location") {
                // and has a location header

                // get absolute redirect Url based on the already known base url
                if let Ok(abs_url) = self.url().join(&String::from_utf8_lossy(location)) {
                    let mut trailing_slash = self.url().as_str().to_string();

                    if !trailing_slash.ends_with('/') {
                        // only append a slash if not present already
                        trailing_slash.push('/');
                    }

                    if trailing_slash == abs_url.as_str() {
                        // if current response's Url + / == the absolute redirection
                        // location, we've found a directory
                        return true;
                    }
                }
            } else {
                // 3xx response without a Location header
                return false;
            }
        } else if self.status_code() >= 200 && self.status_code() < 300 {
            // status code is 2xx, need to check if it ends in /
            if self.url().as_str().ends_with('/') {
                return true;
            }
        }

        false
    }

    /// examine the response's url and grab the file's extension if one is available
    /// to be grabbed.
    #[allow(clippy::missing_panics_doc)]
    #[must_use]
    pub fn extension(&self) -> Option<&str> {
        // path_segments:
        //   Return None for cannot-be-a-base URLs.
        //   When Some is returned, the iterator always contains at least one string
        //     (which may be empty).
        //
        // meaning: the two unwraps here are fine, the worst outcome is an empty string
        let filename = self.url().path_segments().unwrap().next_back().unwrap();

        if !filename.is_empty() {
            // non-empty string, try to get extension
            let parts: Vec<_> = filename
                .split('.')
                // keep things like /.bash_history from becoming an extension
                .filter(|part| !part.is_empty())
                .collect();

            if parts.len() > 1 {
                // filename + at least one extension, i.e. whatever.js becomes ["whatever", "js"]
                return Some(parts.last().unwrap());
            }
        }

        None
    }

    // account for any case variations in header names
    fn get_header_case_insensitive(&self, header_name: &str) -> Option<&Vec<u8>> {
        let lowercase_name = header_name.to_lowercase();

        self.headers()
            .iter()
            .find(|(key, _)| key.to_lowercase() == lowercase_name)
            .map(|(_, value)| value)
    }
}

impl<R> Named for ResponseObserver<R>
where
    R: Response,
{
    fn name(&self) -> &str {
        self.name
    }
}

impl<R> Response for ResponseObserver<R>
where
    R: Response,
{
    /// get the `id` from the associated `Response`
    fn id(&self) -> RequestId {
        self.response.id()
    }

    /// get the `url` from the associated `Response`
    fn url(&self) -> &Url {
        self.response.url()
    }

    /// get the `status_code` from the associated `Response`
    fn status_code(&self) -> u16 {
        self.response.status_code()
    }
    /// get the `headers` from the associated `Response`
    fn headers(&self) -> &HashMap<String, Vec<u8>> {
        self.response.headers()
    }

    /// get the `body` from the associated `Response`
    fn body(&self) -> &[u8] {
        self.response.body()
    }

    /// get the `content_length` from the associated `Response`
    fn content_length(&self) -> usize {
        self.response.content_length()
    }

    /// get the `line_count` from the associated `Response`
    fn line_count(&self) -> usize {
        self.response.line_count()
    }

    /// get the `word_count` from the associated `Response`
    fn word_count(&self) -> usize {
        self.response.word_count()
    }

    /// get the original http request method used to generate the response
    fn method(&self) -> &str {
        self.response.method()
    }

    /// Get the [`Action`] to be taken as a result of this response
    fn action(&self) -> Option<&Action> {
        self.response.action()
    }

    fn request(&self) -> &Request {
        self.response.request()
    }
}

impl<R> Observer for ResponseObserver<R> where R: Response {}

impl<R> ObserverHooks<R> for ResponseObserver<R>
where
    R: Response,
{
    #[instrument(skip_all, fields(%self.name), level = "trace")]
    fn post_send_hook(&mut self, response: R) {
        self.response = response;
    }
}

impl<R> Default for ResponseObserver<R>
where
    R: Response + Default,
{
    fn default() -> Self {
        Self {
            name: RESPONSE_OBSERVER_NAME,
            response: R::default(),
        }
    }
}

cfg_if! {
    if #[cfg(feature = "async")] {
        use crate::responses::AsyncResponse;

        impl From<AsyncResponse> for ResponseObserver<AsyncResponse> {
            fn from(response: AsyncResponse) -> Self {
                Self::with_response(response)
            }
        }
    }
}

cfg_if! {
    if #[cfg(feature = "blocking")] {
        use crate::responses::BlockingResponse;

        impl From<BlockingResponse> for ResponseObserver<BlockingResponse> {
            fn from(response: BlockingResponse) -> Self {
                Self::with_response(response)
            }
        }
    }

}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::error::FeroxFuzzError;
    use crate::responses::AsyncResponse;
    use http::response;
    use std::time::Duration;

    #[tokio::test]
    async fn test_get_header_case_insensitive() -> Result<(), FeroxFuzzError> {
        // Create a response with headers in different cases

        let reqwest_response = response::Builder::new()
            .status(200)
            .header("Content-Type", "text/html")
            .header("X-Custom-Header", "CustomValue")
            .header("accept-encoding", "gzip")
            .body("")
            .unwrap();

        let elapsed = Duration::from_secs(1);

        let response = AsyncResponse::try_from_reqwest_response(
            Request::default(),
            reqwest_response.into(),
            elapsed,
        )
        .await?;

        let observer = ResponseObserver::with_response(response);

        // Test exact case match
        assert_eq!(
            observer.get_header_case_insensitive("Content-Type"),
            Some(&b"text/html".to_vec())
        );

        // Test different case variations
        assert_eq!(
            observer.get_header_case_insensitive("content-type"),
            Some(&b"text/html".to_vec())
        );
        assert_eq!(
            observer.get_header_case_insensitive("CONTENT-TYPE"),
            Some(&b"text/html".to_vec())
        );
        assert_eq!(
            observer.get_header_case_insensitive("CoNtEnT-tYpE"),
            Some(&b"text/html".to_vec())
        );

        // Test another header with mixed case
        assert_eq!(
            observer.get_header_case_insensitive("x-custom-header"),
            Some(&b"CustomValue".to_vec())
        );
        assert_eq!(
            observer.get_header_case_insensitive("X-CUSTOM-HEADER"),
            Some(&b"CustomValue".to_vec())
        );

        // Test lowercase header
        assert_eq!(
            observer.get_header_case_insensitive("ACCEPT-ENCODING"),
            Some(&b"gzip".to_vec())
        );

        // Test header that doesn't exist
        assert_eq!(
            observer.get_header_case_insensitive("non-existent-header"),
            None
        );

        Ok(())
    }

    #[tokio::test]
    async fn test_is_redirect_with_case_variations() -> Result<(), FeroxFuzzError> {
        // Create a response with Location header in lowercase

        let reqwest_response = response::Builder::new()
            .status(302)
            .header("location", "/redirect")
            .body("")
            .unwrap();

        let elapsed = Duration::from_secs(1);

        let response = AsyncResponse::try_from_reqwest_response(
            Request::default(),
            reqwest_response.into(),
            elapsed,
        )
        .await?;

        let observer_lowercase = ResponseObserver::with_response(response);

        assert!(observer_lowercase.is_redirect());

        // Create a response with Location header in uppercase
        let reqwest_response = response::Builder::new()
            .status(302)
            .header("LOCaTION", "/redirect")
            .body("")
            .unwrap();

        let response = AsyncResponse::try_from_reqwest_response(
            Request::default(),
            reqwest_response.into(),
            elapsed,
        )
        .await?;

        let observer_uppercase = ResponseObserver::with_response(response);

        // This should still pass with the current implementation, which only checks for "Location" and "location"
        // If we update is_redirect to use get_header_case_insensitive, this test would still pass
        assert!(observer_uppercase.is_redirect());

        Ok(())
    }
}