Skip to main content

fallow_security/
predicates.rs

1//! Literal, object and call-option gates of a catalogue row.
2
3use fallow_types::extract::{SinkCallOptions, SinkLiteralValue, SinkObjectProperty};
4
5use crate::Matcher;
6
7impl Matcher {
8    /// Whether captured literal metadata satisfies this row's literal gates.
9    #[must_use]
10    pub fn literal_value_satisfied(&self, literal: Option<&SinkLiteralValue>) -> bool {
11        if self.literal_values.is_empty()
12            && self.literal_contains.is_empty()
13            && self.literal_integers.is_empty()
14        {
15            return true;
16        }
17        let string_satisfied = (self.literal_values.is_empty() && self.literal_contains.is_empty())
18            || match literal {
19                Some(SinkLiteralValue::String(value)) => {
20                    let lower = value.to_ascii_lowercase();
21                    (self.literal_values.is_empty()
22                        || self
23                            .literal_values
24                            .iter()
25                            .any(|expected| lower == expected.to_ascii_lowercase()))
26                        && (self.literal_contains.is_empty()
27                            || self
28                                .literal_contains
29                                .iter()
30                                .any(|needle| lower.contains(&needle.to_ascii_lowercase())))
31                }
32                _ => false,
33            };
34        let integer_satisfied = self.literal_integers.is_empty()
35            || match literal {
36                Some(SinkLiteralValue::Integer(value)) => self.literal_integers.contains(value),
37                _ => false,
38            };
39        string_satisfied && integer_satisfied
40    }
41
42    /// Whether captured object-literal metadata satisfies this row's object
43    /// property gates.
44    #[must_use]
45    pub fn object_properties_satisfied(&self, properties: &[SinkObjectProperty]) -> bool {
46        if self.object_properties.is_empty() && self.object_missing_or_false.is_empty() {
47            return true;
48        }
49        for predicate in &self.object_properties {
50            let Some(property) = properties.iter().find(|p| p.key == predicate.key) else {
51                return false;
52            };
53            if !predicate.value.matches(&property.value) {
54                return false;
55            }
56        }
57        if self.object_missing_or_false.is_empty() {
58            return true;
59        }
60        self.object_missing_or_false.iter().any(|key| {
61            properties
62                .iter()
63                .find(|p| p.key == *key)
64                .is_none_or(|property| matches!(property.value, SinkLiteralValue::Boolean(false)))
65        })
66    }
67
68    /// Whether missing-key predicates are satisfied by complete static object
69    /// key metadata.
70    #[must_use]
71    pub fn object_missing_satisfied(&self, keys: &[String], keys_complete: bool) -> bool {
72        if self.object_missing.is_empty() {
73            return true;
74        }
75        keys_complete && self.object_missing.iter().any(|key| !keys.contains(key))
76    }
77
78    /// Whether the call options of a sink can enable one of this row's
79    /// `options_may_enable` options. Unknown options (`None`, an options
80    /// variable, a spread) can enable them. Known options cannot when each
81    /// listed option is absent or the literal `false`.
82    #[must_use]
83    pub fn options_may_enable_satisfied(&self, options: Option<&SinkCallOptions>) -> bool {
84        if self.options_may_enable.is_empty() {
85            return true;
86        }
87        let Some(options) = options else {
88            return true;
89        };
90        if !options.keys_complete {
91            return true;
92        }
93        self.options_may_enable.iter().any(|key| {
94            options.keys.contains(key)
95                && !options.properties.iter().any(|property| {
96                    property.key == *key
97                        && matches!(property.value, SinkLiteralValue::Boolean(false))
98                })
99        })
100    }
101
102    /// Whether the call options of a sink prove that one of this row's
103    /// `options_enabled` options is on: a complete options object literal
104    /// sets it to `true` or to a non-empty string (a shell path). Unknown
105    /// options do not satisfy the gate.
106    #[must_use]
107    pub fn options_enabled_satisfied(&self, options: Option<&SinkCallOptions>) -> bool {
108        if self.options_enabled.is_empty() {
109            return true;
110        }
111        let Some(options) = options.filter(|options| options.keys_complete) else {
112            return false;
113        };
114        self.options_enabled.iter().any(|key| {
115            options.properties.iter().any(|property| {
116                property.key == *key
117                    && match &property.value {
118                        SinkLiteralValue::Boolean(value) => *value,
119                        SinkLiteralValue::String(value) => !value.is_empty(),
120                        SinkLiteralValue::Integer(_) | SinkLiteralValue::Null => false,
121                    }
122            })
123        })
124    }
125
126    /// Whether captured context names satisfy this row's context keyword gate.
127    #[must_use]
128    pub fn context_satisfied(&self, context_names: &[String]) -> bool {
129        if self.context_keywords.is_empty() {
130            return true;
131        }
132        context_names.iter().any(|name| {
133            let lower = name.to_ascii_lowercase();
134            self.context_keywords
135                .iter()
136                .any(|keyword| lower.contains(&keyword.to_ascii_lowercase()))
137        })
138    }
139}
140
141#[cfg(test)]
142#[expect(
143    clippy::expect_used,
144    reason = "the test asserts a catalogue invariant directly"
145)]
146mod tests {
147    use super::*;
148    use crate::catalogue;
149
150    #[test]
151    fn options_may_enable_needs_proof_that_the_option_is_off() {
152        let shell_spawn = catalogue()
153            .matchers()
154            .iter()
155            .find(|m| m.options_may_enable == ["shell"])
156            .expect("spawn shell row present");
157        let options =
158            |keys: &[&str], properties: Vec<SinkObjectProperty>, complete: bool| SinkCallOptions {
159                properties,
160                keys: keys.iter().map(ToString::to_string).collect(),
161                keys_complete: complete,
162            };
163        let shell = |value: SinkLiteralValue| SinkObjectProperty {
164            key: "shell".to_string(),
165            value,
166        };
167
168        assert!(
169            !shell_spawn.is_literal_aware(),
170            "options_may_enable keeps the non-literal command gate"
171        );
172        assert!(shell_spawn.options_may_enable_satisfied(None));
173        assert!(shell_spawn.options_may_enable_satisfied(Some(&options(&[], vec![], false))));
174        assert!(shell_spawn.options_may_enable_satisfied(Some(&options(
175            &["shell"],
176            vec![shell(SinkLiteralValue::Boolean(true))],
177            true,
178        ))));
179        assert!(shell_spawn.options_may_enable_satisfied(Some(&options(
180            &["shell"],
181            vec![shell(SinkLiteralValue::String("/bin/bash".to_string()))],
182            true,
183        ))));
184        assert!(
185            shell_spawn.options_may_enable_satisfied(Some(&options(&["shell"], vec![], true))),
186            "a non-literal shell value can enable the shell"
187        );
188        assert!(!shell_spawn.options_may_enable_satisfied(Some(&options(&[], vec![], true))));
189        assert!(!shell_spawn.options_may_enable_satisfied(Some(&options(
190            &["stdio"],
191            vec![],
192            true,
193        ))));
194        assert!(!shell_spawn.options_may_enable_satisfied(Some(&options(
195            &["shell"],
196            vec![shell(SinkLiteralValue::Boolean(false))],
197            true,
198        ))));
199    }
200
201    #[test]
202    fn options_enabled_needs_proof_that_the_option_is_on() {
203        let shell_args = catalogue()
204            .matchers()
205            .iter()
206            .find(|m| m.options_enabled == ["shell"])
207            .expect("shell argument row present");
208        let options = |properties: Vec<SinkObjectProperty>, complete: bool| SinkCallOptions {
209            keys: properties.iter().map(|p| p.key.clone()).collect(),
210            properties,
211            keys_complete: complete,
212        };
213        let shell = |value: SinkLiteralValue| SinkObjectProperty {
214            key: "shell".to_string(),
215            value,
216        };
217
218        assert_eq!(shell_args.arg_index, 1);
219        assert!(shell_args.requires_source);
220        assert!(shell_args.options_enabled_satisfied(Some(&options(
221            vec![shell(SinkLiteralValue::Boolean(true))],
222            true,
223        ))));
224        assert!(shell_args.options_enabled_satisfied(Some(&options(
225            vec![shell(SinkLiteralValue::String("/bin/sh".to_string()))],
226            true,
227        ))));
228        assert!(!shell_args.options_enabled_satisfied(None));
229        assert!(!shell_args.options_enabled_satisfied(Some(&options(vec![], true))));
230        assert!(!shell_args.options_enabled_satisfied(Some(&options(
231            vec![shell(SinkLiteralValue::Boolean(false))],
232            true,
233        ))));
234        assert!(!shell_args.options_enabled_satisfied(Some(&options(
235            vec![shell(SinkLiteralValue::String(String::new()))],
236            true,
237        ))));
238        assert!(
239            !shell_args.options_enabled_satisfied(Some(&options(
240                vec![shell(SinkLiteralValue::Boolean(true))],
241                false,
242            ))),
243            "a spread or a duplicate key can turn the shell off again"
244        );
245    }
246}