antissrf 0.1.1

Rust implementation of Microsoft AntiSSRF
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223

//! Error types for AntiSSRF operations.
//!
//! Every fallible operation in this crate returns [`AntiSSRFError`], a single
//! enum that covers validation failures, configuration mistakes, and runtime
//! policy violations. The error type implements [`std::error::Error`] via
//! `thiserror`, and is [`Clone`] + [`PartialEq`] so it can be cheaply passed
//! around and compared in tests.
//!
//! # Error categories
//!
//! | Variant | Triggered by | Typical cause |
//! |---------|--------------|---------------|
//! | [`IPDisallowed`](AntiSSRFError::IPDisallowed) | [`AntiSSRFPolicy::validate_request`](crate::policy::AntiSSRFPolicy::validate_request), DNS resolution, redirects | Target IP is in a denylist or not in the allowlist |
//! | [`SchemeDisallowed`](AntiSSRFError::SchemeDisallowed) | [`AntiSSRFPolicy::validate_request`](crate::policy::AntiSSRFPolicy::validate_request) | `http://` used when [`set_allow_plaintext_http`](crate::policy::AntiSSRFPolicy::set_allow_plaintext_http) is `false` |
//! | [`HeaderDenied`](AntiSSRFError::HeaderDenied) | [`AntiSSRFPolicy::validate_request`](crate::policy::AntiSSRFPolicy::validate_request) | Request contains a header in the denylist |
//! | [`HeaderRequired`](AntiSSRFError::HeaderRequired) | [`AntiSSRFPolicy::validate_request`](crate::policy::AntiSSRFPolicy::validate_request) | Request is missing a header in the required list |
//! | [`InvalidHeader`](AntiSSRFError::InvalidHeader) | [`AntiSSRFPolicy`](crate::policy::AntiSSRFPolicy) configuration methods | Empty or malformed header name supplied at build time |
//! | [`PolicyLocked`](AntiSSRFError::PolicyLocked) | Mutating a locked [`AntiSSRFPolicy`](crate::policy::AntiSSRFPolicy) | Attempting to modify a policy after it has been used |
//! | [`ConflictingConfiguration`](AntiSSRFError::ConflictingConfiguration) | [`AntiSSRFPolicy`](crate::policy::AntiSSRFPolicy) configuration methods | Logically incompatible options (e.g. denylist + `deny_all_unspecified_ips`) |
//! | [`InvalidCIDR`](AntiSSRFError::InvalidCIDR) | [`CIDRBlock::parse`](crate::CIDRBlock::parse) | Malformed CIDR string such as `10.0.0.0/33` |
//! | [`InvalidIP`](AntiSSRFError::InvalidIP) | IP parsing helpers | String that does not represent a valid IPv4 or IPv6 address |
//! | [`InvalidURL`](AntiSSRFError::InvalidURL) | URL parsing helpers | String that is not a valid URL |
//! | [`RedirectValidationFailed`](AntiSSRFError::RedirectValidationFailed) | [`network`](crate::network) middleware | A redirect Location failed re-validation against the active policy |
//!
//! # Example
//!
//! ```
//! use antissrf::{AntiSSRFPolicy, PolicyConfigOptions, AntiSSRFError};
//!
//! # fn main() -> Result<(), AntiSSRFError> {
//! let mut policy = AntiSSRFPolicy::new(PolicyConfigOptions::ExternalOnlyLatest);
//! policy.set_allow_plaintext_http(false)?;
//!
//! let mut headers = vec![];
//! match policy.validate_request("http:", &mut headers) {
//!     Err(AntiSSRFError::SchemeDisallowed) => {
//!         // plaintext HTTP rejected
//!     }
//!     Err(AntiSSRFError::IPDisallowed) => {
//!         // IMDS address blocked
//!     }
//!     Ok(_) => {}
//!     Err(e) => panic!("unexpected error: {}", e),
//! }
//! # Ok(())
//! # }
//! ```

use thiserror::Error;

/// Error types for AntiSSRF operations.
///
/// See the [module-level documentation](self) for a mapping of each variant to
/// the policy setting or API operation that triggers it.
#[derive(Error, Debug, Clone, PartialEq)]
pub enum AntiSSRFError {
    /// The target IP address is blocked by the active policy.
    ///
    /// Returned by [`AntiSSRFPolicy::validate_request`](crate::policy::AntiSSRFPolicy::validate_request)
    /// and the network middleware when the resolved IP falls inside a denylist
    /// (or outside the allowlist when [`deny_all_unspecified_ips`](crate::policy::AntiSSRFPolicy::deny_all_unspecified_ips)
    /// is enabled).
    #[error("IP address disallowed by policy")]
    IPDisallowed,

    /// The request scheme is blocked by the active policy.
    ///
    /// Common causes:
    /// - Plaintext `http://` is used while [`set_allow_plaintext_http`](crate::policy::AntiSSRFPolicy::set_allow_plaintext_http)
    ///   is `false`.
    /// - A non-HTTP scheme such as `ftp:` or `file:` is requested.
    #[error("Request scheme disallowed by policy")]
    SchemeDisallowed,

    /// A denied HTTP header was present in the request.
    ///
    /// Set the denied header list via
    /// [`add_denied_headers`](crate::policy::AntiSSRFPolicy::add_denied_headers).
    /// Comparison is case-insensitive for header names.
    #[error("Request header disallowed by policy")]
    HeaderDenied,

    /// A required HTTP header was missing from the request.
    ///
    /// Set the required header list via
    /// [`add_required_headers`](crate::policy::AntiSSRFPolicy::add_required_headers).
    /// Comparison is case-insensitive for header names.
    #[error("Required request header missing")]
    HeaderRequired,

    /// An invalid or empty header name was provided during policy configuration.
    ///
    /// Header names must be non-empty and contain only printable ASCII characters
    /// excluding the colon (`:`).
    #[error("Invalid header name")]
    InvalidHeader,

    /// Custom DNS lookup functions are not permitted for security reasons.
    ///
    /// The network middleware must control name resolution to ensure IP validation
    /// happens after resolution and before the TCP handshake.
    #[error("Cannot use AntiSSRF with custom lookup function")]
    CustomLookupNotAllowed,

    /// The policy has been locked and can no longer be modified.
    ///
    /// Policies are automatically locked on first use (e.g. the first call to
    /// [`validate_request`](crate::policy::AntiSSRFPolicy::validate_request) or
    /// the first request made through the network middleware). Create a new
    /// [`AntiSSRFPolicy`](crate::policy::AntiSSRFPolicy) if you
    /// need different settings.
    #[error("Policy is locked and cannot be modified")]
    PolicyLocked,

    /// A logically incompatible combination of policy options was requested.
    ///
    /// For example, adding explicit denied addresses while
    /// [`deny_all_unspecified_ips`](crate::policy::AntiSSRFPolicy::deny_all_unspecified_ips)
    /// is already enabled is redundant and therefore rejected.
    #[error("Conflicting policy configuration")]
    ConflictingConfiguration,

    /// The supplied string is not a valid CIDR block.
    ///
    /// Valid examples: `192.168.0.0/24`, `::1/128`, `10.0.0.0/8`.
    /// Invalid examples: `10.0.0.0/33` (prefix too large), `not-an-ip/24`.
    #[error("Invalid CIDR block: {0}")]
    InvalidCIDR(String),

    /// The supplied string is not a valid IP address.
    ///
    /// Valid examples: `192.168.1.1`, `::1`, `::ffff:192.168.1.1`.
    #[error("Invalid IP address: {0}")]
    InvalidIP(String),

    /// The supplied string is not a valid URL.
    ///
    /// URLs must include a scheme and host. Valid examples:
    /// `https://example.com/path`, `http://10.0.0.1:8080/`.
    #[error("Invalid URL: {0}")]
    InvalidURL(String),

    /// A redirect in the HTTP response chain failed re-validation.
    ///
    /// The network middleware re-runs the active policy against every
    /// `Location` header in a 3xx redirect. If the new URL is blocked,
    /// this error is returned and the redirect is aborted.
    #[error("Redirect validation failed: {0}")]
    RedirectValidationFailed(String),
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn error_display_messages() {
        assert_eq!(
            AntiSSRFError::IPDisallowed.to_string(),
            "IP address disallowed by policy"
        );
        assert_eq!(
            AntiSSRFError::SchemeDisallowed.to_string(),
            "Request scheme disallowed by policy"
        );
        assert_eq!(
            AntiSSRFError::HeaderDenied.to_string(),
            "Request header disallowed by policy"
        );
        assert_eq!(
            AntiSSRFError::HeaderRequired.to_string(),
            "Required request header missing"
        );
        assert_eq!(
            AntiSSRFError::InvalidHeader.to_string(),
            "Invalid header name"
        );
        assert_eq!(
            AntiSSRFError::CustomLookupNotAllowed.to_string(),
            "Cannot use AntiSSRF with custom lookup function"
        );
        assert_eq!(
            AntiSSRFError::PolicyLocked.to_string(),
            "Policy is locked and cannot be modified"
        );
        assert_eq!(
            AntiSSRFError::ConflictingConfiguration.to_string(),
            "Conflicting policy configuration"
        );
        assert_eq!(
            AntiSSRFError::InvalidCIDR("10.0.0.0/33".to_string()).to_string(),
            "Invalid CIDR block: 10.0.0.0/33"
        );
        assert_eq!(
            AntiSSRFError::InvalidIP("not-an-ip".to_string()).to_string(),
            "Invalid IP address: not-an-ip"
        );
        assert_eq!(
            AntiSSRFError::InvalidURL("not-a-url".to_string()).to_string(),
            "Invalid URL: not-a-url"
        );
        assert_eq!(
            AntiSSRFError::RedirectValidationFailed("http://127.0.0.1/secret".to_string()).to_string(),
            "Redirect validation failed: http://127.0.0.1/secret"
        );
    }

    #[test]
    fn error_clonable() {
        let err = AntiSSRFError::IPDisallowed;
        let cloned = err.clone();
        assert_eq!(err, cloned);
    }

    #[test]
    fn error_partial_eq() {
        assert_eq!(AntiSSRFError::PolicyLocked, AntiSSRFError::PolicyLocked);
        assert_ne!(
            AntiSSRFError::IPDisallowed,
            AntiSSRFError::SchemeDisallowed
        );
    }
}