oxigeo-security 0.2.3

Enterprise security features for OxiGeo: encryption, access control, compliance
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
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
//! Malware scanning.
//!
//! A dependency-free, Pure-Rust malware scanner that performs real inspection of file
//! content rather than reporting a fabricated "clean" result. It combines four independent
//! detection strategies:
//!
//! 1. **Known-signature matching** — the industry-standard EICAR anti-malware test file and
//!    other embedded byte signatures are matched directly against the content.
//! 2. **Hash blocklisting** — the SHA-256 of the content is compared against a caller-supplied
//!    set of known-bad digests.
//! 3. **Magic-byte / executable heuristics** — executable payloads (ELF, PE/MZ, Mach-O,
//!    shell/script shebangs) embedded in data are flagged as suspicious.
//! 4. **Entropy heuristic** — content whose Shannon entropy is close to the 8-bits-per-byte
//!    ceiling (typical of packed or encrypted payloads) is flagged for review.
//!
//! For an actual antivirus engine's signature depth you would layer a commercial/OSS engine
//! behind a feature flag, but the checks here are genuine: identical malicious and benign
//! inputs produce demonstrably different results.

use crate::error::{Result, SecurityError};
use crate::scanning::{Finding, ScanResult, ScanType, Severity};
use sha2::{Digest, Sha256};
use std::collections::HashSet;

/// Maximum number of bytes read from a file for scanning.
///
/// Bounds memory for pathological inputs; the leading region of a file is where magic
/// bytes and the overwhelming majority of signatures live, and entropy over the sampled
/// region is representative.
const MAX_SCAN_BYTES: usize = 16 * 1024 * 1024;

/// Entropy (bits/byte) at or above which content is flagged as suspiciously high-entropy.
const HIGH_ENTROPY_THRESHOLD: f64 = 7.5;

/// Minimum size (bytes) before the entropy heuristic is applied. Tiny inputs trivially have
/// misleading entropy, so we ignore them.
const ENTROPY_MIN_SIZE: usize = 256;

/// The canonical EICAR anti-malware test string (a harmless file every real AV engine is
/// required to detect). Split so this source file itself is not flagged by scanners.
const EICAR_SIGNATURE: &[u8] =
    br#"X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*"#;

/// A byte signature matched literally against the scanned content.
struct ByteSignature {
    /// Human-readable name of what the signature detects.
    name: &'static str,
    /// Raw bytes to search for.
    needle: &'static [u8],
    /// Severity assigned when matched.
    severity: Severity,
}

/// Malware scanner.
pub struct MalwareScanner {
    /// SHA-256 digests (lowercase hex) of known-bad content.
    hash_blocklist: HashSet<String>,
    /// Whether the executable-magic-byte heuristic is enabled.
    detect_executables: bool,
    /// Whether the high-entropy heuristic is enabled.
    detect_high_entropy: bool,
}

impl MalwareScanner {
    /// Create new malware scanner with the default detection strategies enabled.
    pub fn new() -> Self {
        Self {
            hash_blocklist: HashSet::new(),
            detect_executables: true,
            detect_high_entropy: true,
        }
    }

    /// Add a known-bad SHA-256 digest (hex, case-insensitive) to the blocklist.
    pub fn with_blocklisted_sha256(mut self, digest_hex: impl AsRef<str>) -> Self {
        self.hash_blocklist
            .insert(digest_hex.as_ref().trim().to_ascii_lowercase());
        self
    }

    /// Enable or disable the executable-magic-byte heuristic.
    pub fn detect_executables(mut self, enabled: bool) -> Self {
        self.detect_executables = enabled;
        self
    }

    /// Enable or disable the high-entropy heuristic.
    pub fn detect_high_entropy(mut self, enabled: bool) -> Self {
        self.detect_high_entropy = enabled;
        self
    }

    /// Scan a file for malware.
    ///
    /// Reads the file (bounded by `MAX_SCAN_BYTES`) and inspects its content. Returns a
    /// typed [`SecurityError`] when the file cannot be read — never a fabricated clean
    /// result for a file that was never opened.
    pub fn scan_file(&self, file_path: &str) -> Result<ScanResult> {
        let metadata = std::fs::metadata(file_path)
            .map_err(|e| SecurityError::security_scan(format!("cannot stat '{file_path}': {e}")))?;

        let file = std::fs::File::open(file_path)
            .map_err(|e| SecurityError::security_scan(format!("cannot open '{file_path}': {e}")))?;

        use std::io::Read;
        let mut buf = Vec::new();
        file.take(MAX_SCAN_BYTES as u64)
            .read_to_end(&mut buf)
            .map_err(|e| SecurityError::security_scan(format!("cannot read '{file_path}': {e}")))?;

        Ok(self.scan_bytes_named(&buf, Some(file_path), metadata.len()))
    }

    /// Scan an in-memory byte buffer for malware, returning a [`ScanResult`].
    pub fn scan_bytes(&self, data: &[u8]) -> ScanResult {
        self.scan_bytes_named(data, None, data.len() as u64)
    }

    fn scan_bytes_named(&self, data: &[u8], location: Option<&str>, full_size: u64) -> ScanResult {
        let mut findings = Vec::new();

        // 1. Literal byte-signature matches (EICAR + embedded-PE marker).
        for signature in Self::byte_signatures() {
            if Self::contains(data, signature.needle) {
                findings.push(Finding {
                    id: Self::finding_id(location, "signature", signature.name),
                    severity: signature.severity,
                    description: format!("Malware signature detected: {}", signature.name),
                    location: location.map(|l| l.to_string()),
                });
            }
        }

        // 2. Hash blocklist (SHA-256 over the scanned bytes).
        if !self.hash_blocklist.is_empty() {
            let digest = Self::sha256_hex(data);
            if self.hash_blocklist.contains(&digest) {
                findings.push(Finding {
                    id: Self::finding_id(location, "hash", &digest),
                    severity: Severity::Critical,
                    description: format!("Content matches blocklisted SHA-256: {digest}"),
                    location: location.map(|l| l.to_string()),
                });
            }
        }

        // 3. Executable magic-byte heuristic.
        if self.detect_executables
            && let Some(kind) = Self::executable_kind(data)
        {
            findings.push(Finding {
                id: Self::finding_id(location, "executable", kind),
                severity: Severity::Medium,
                description: format!(
                    "Executable content detected ({kind}); unexpected in scanned data"
                ),
                location: location.map(|l| l.to_string()),
            });
        }

        // 4. Entropy heuristic (packed / encrypted payloads).
        if self.detect_high_entropy && data.len() >= ENTROPY_MIN_SIZE {
            let entropy = Self::shannon_entropy(data);
            if entropy >= HIGH_ENTROPY_THRESHOLD {
                findings.push(Finding {
                    id: Self::finding_id(location, "entropy", "high"),
                    severity: Severity::Low,
                    description: format!(
                        "High Shannon entropy ({entropy:.2} bits/byte over {} bytes); \
                         possibly packed or encrypted content",
                        data.len()
                    ),
                    location: location.map(|l| l.to_string()),
                });
            }
        }

        // Note truncation so a caller knows only a prefix was inspected.
        if full_size > data.len() as u64 {
            findings.push(Finding {
                id: Self::finding_id(location, "truncated", "scan"),
                severity: Severity::Info,
                description: format!(
                    "Only the first {} of {full_size} bytes were scanned",
                    data.len()
                ),
                location: location.map(|l| l.to_string()),
            });
        }

        ScanResult {
            scan_type: ScanType::Malware,
            findings,
            scanned_at: chrono::Utc::now(),
        }
    }

    fn byte_signatures() -> [ByteSignature; 2] {
        [
            ByteSignature {
                name: "EICAR-Test-File",
                needle: EICAR_SIGNATURE,
                severity: Severity::Critical,
            },
            ByteSignature {
                name: "Embedded-PE-DOS-stub",
                needle: b"This program cannot be run in DOS mode",
                severity: Severity::Medium,
            },
        ]
    }

    /// Identifies well-known executable container formats by magic bytes.
    fn executable_kind(data: &[u8]) -> Option<&'static str> {
        if data.starts_with(b"\x7fELF") {
            return Some("ELF");
        }
        if data.starts_with(b"MZ") {
            return Some("PE/MZ");
        }
        // Mach-O (32/64-bit, big/little endian) and universal ("fat") binaries.
        const MACHO: [&[u8]; 5] = [
            &[0xFE, 0xED, 0xFA, 0xCE],
            &[0xFE, 0xED, 0xFA, 0xCF],
            &[0xCE, 0xFA, 0xED, 0xFE],
            &[0xCF, 0xFA, 0xED, 0xFE],
            &[0xCA, 0xFE, 0xBA, 0xBE],
        ];
        if MACHO.iter().any(|m| data.starts_with(m)) {
            return Some("Mach-O");
        }
        if data.starts_with(b"#!") {
            return Some("script-shebang");
        }
        None
    }

    /// Shannon entropy in bits per byte over `data`.
    fn shannon_entropy(data: &[u8]) -> f64 {
        if data.is_empty() {
            return 0.0;
        }
        let mut counts = [0u64; 256];
        for &b in data {
            counts[b as usize] += 1;
        }
        let len = data.len() as f64;
        let mut entropy = 0.0;
        for &count in counts.iter() {
            if count == 0 {
                continue;
            }
            let p = count as f64 / len;
            entropy -= p * p.log2();
        }
        entropy
    }

    fn sha256_hex(data: &[u8]) -> String {
        let mut hasher = Sha256::new();
        hasher.update(data);
        let digest = hasher.finalize();
        let mut out = String::with_capacity(64);
        for byte in digest {
            use std::fmt::Write;
            let _ = write!(out, "{byte:02x}");
        }
        out
    }

    /// Substring (byte) search.
    fn contains(haystack: &[u8], needle: &[u8]) -> bool {
        if needle.is_empty() || needle.len() > haystack.len() {
            return needle.is_empty();
        }
        haystack
            .windows(needle.len())
            .any(|window| window == needle)
    }

    fn finding_id(location: Option<&str>, category: &str, detail: &str) -> String {
        match location {
            Some(loc) => format!("malware:{category}:{detail}:{loc}"),
            None => format!("malware:{category}:{detail}"),
        }
    }
}

impl Default for MalwareScanner {
    fn default() -> Self {
        Self::new()
    }
}

#[cfg(test)]
mod tests {
    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]

    use super::*;
    use std::io::Write;

    #[test]
    fn test_clean_text_has_no_findings() {
        let scanner = MalwareScanner::new();
        let result = scanner.scan_bytes(b"just some perfectly ordinary plain text content");
        assert_eq!(result.scan_type, ScanType::Malware);
        assert!(
            result.findings.is_empty(),
            "benign text should produce no findings, got {:?}",
            result.findings
        );
    }

    #[test]
    fn test_eicar_is_detected_critical() {
        let scanner = MalwareScanner::new();
        // Reconstruct the EICAR string at runtime so the constant match path is exercised.
        let result = scanner.scan_bytes(EICAR_SIGNATURE);
        assert!(
            result
                .findings
                .iter()
                .any(|f| f.severity == Severity::Critical && f.description.contains("EICAR")),
            "EICAR test file must be detected as Critical, got {:?}",
            result.findings
        );
    }

    #[test]
    fn test_elf_magic_flagged() {
        let scanner = MalwareScanner::new();
        let mut data = b"\x7fELF".to_vec();
        data.extend_from_slice(&[0u8; 64]);
        let result = scanner.scan_bytes(&data);
        assert!(
            result
                .findings
                .iter()
                .any(|f| f.description.contains("ELF")),
            "ELF executable should be flagged"
        );
    }

    #[test]
    fn test_hash_blocklist_matches() {
        let payload = b"totally benign but blocklisted";
        let digest = MalwareScanner::sha256_hex(payload);
        let scanner = MalwareScanner::new().with_blocklisted_sha256(&digest);
        let result = scanner.scan_bytes(payload);
        assert!(
            result
                .findings
                .iter()
                .any(|f| f.severity == Severity::Critical && f.description.contains("blocklisted")),
            "blocklisted hash must produce a Critical finding"
        );

        // A different payload with the same scanner must NOT match.
        let clean = scanner.scan_bytes(b"different content entirely");
        assert!(
            clean
                .findings
                .iter()
                .all(|f| !f.description.contains("blocklisted"))
        );
    }

    #[test]
    fn test_high_entropy_flagged() {
        let scanner = MalwareScanner::new();
        // A pseudo-random-ish buffer with near-maximal entropy.
        let mut data = Vec::with_capacity(4096);
        let mut x: u32 = 0x1234_5678;
        for _ in 0..4096 {
            x = x.wrapping_mul(1_664_525).wrapping_add(1_013_904_223);
            data.push((x >> 24) as u8);
        }
        let result = scanner.scan_bytes(&data);
        assert!(
            result
                .findings
                .iter()
                .any(|f| f.description.contains("entropy")),
            "high-entropy content should be flagged"
        );
    }

    #[test]
    fn test_scan_file_reads_real_file() {
        let mut path = std::env::temp_dir();
        path.push(format!(
            "oxigeo_malware_scan_test_{}.bin",
            std::process::id()
        ));
        {
            let mut f = std::fs::File::create(&path).expect("create temp file");
            f.write_all(EICAR_SIGNATURE).expect("write");
        }

        let scanner = MalwareScanner::new();
        let result = scanner
            .scan_file(path.to_str().expect("path utf8"))
            .expect("scan should succeed for a readable file");
        assert!(
            result
                .findings
                .iter()
                .any(|f| f.description.contains("EICAR")),
            "scan_file must actually read and inspect the file"
        );

        let _ = std::fs::remove_file(&path);
    }

    #[test]
    fn test_scan_file_missing_errors() {
        let scanner = MalwareScanner::new();
        let mut path = std::env::temp_dir();
        path.push(format!(
            "oxigeo_definitely_missing_file_{}.bin",
            std::process::id()
        ));
        let result = scanner.scan_file(path.to_str().expect("path utf8"));
        assert!(
            result.is_err(),
            "a missing file must produce a typed error, not a fake clean result"
        );
    }
}