malwaredb_server/db/
types.rs

1// SPDX-License-Identifier: Apache-2.0
2
3use malwaredb_api::{SupportedFileType, SupportedFileTypes};
4use malwaredb_types::utils::EntropyCalc;
5
6use fuzzyhash::FuzzyHash;
7use human_hash::humanize;
8use magic::cookie::DatabasePaths;
9use malwaredb_lzjd2::lzjd::LzDigest;
10use md5::Md5;
11use sha1::Sha1;
12use sha2::{Digest, Sha256, Sha384, Sha512};
13use tlsh_fixed::TlshBuilder;
14use tracing::error;
15use uuid::Uuid;
16
17/// Metadata about a file for storing as a record in Malware DB
18#[derive(Debug, Clone)]
19pub struct FileMetadata {
20    /// File name
21    pub name: Option<String>,
22
23    /// File size in bytes
24    pub size: u64,
25
26    /// Entropy of the file
27    pub entropy: f32,
28
29    /// SHA-1 hash
30    pub sha1: Vec<u8>,
31
32    /// SHA-256 hash
33    pub sha256: Vec<u8>,
34
35    /// SHA-384 hash
36    pub sha384: Vec<u8>,
37
38    /// SHA-512 hash
39    pub sha512: Vec<u8>,
40
41    /// MD5 hash
42    pub md5: Uuid,
43
44    /// `LZJD` similarity hash
45    pub lzjd: Option<String>,
46
47    /// `SSDeep` similarity hash, if the file is large enough
48    pub ssdeep: Option<String>,
49
50    /// Trend Micro's similarity hash (distance metric)
51    pub tlsh: Option<String>,
52
53    /// Human Hash, based on <https://github.com/zacharyvoase/humanhash>
54    pub humanhash: String,
55
56    /// File command (or libmagic) description of the file
57    pub file_command: String,
58}
59
60impl FileMetadata {
61    /// Get the collection of file measurements given a byte sequence
62    ///
63    /// # Panics
64    ///
65    /// This won't actually panic despite a call to `.unwrap()` because the input to that function
66    /// is known to always be the correct size.
67    pub fn new(contents: &[u8], name: Option<&str>) -> Self {
68        let mut sha1 = Sha1::new();
69        sha1.update(contents);
70        let sha1 = sha1.finalize();
71
72        let mut sha256 = Sha256::new();
73        sha256.update(contents);
74        let sha256 = sha256.finalize();
75
76        let mut sha384 = Sha384::new();
77        sha384.update(contents);
78        let sha384 = sha384.finalize();
79
80        let mut sha512 = Sha512::new();
81        sha512.update(contents);
82        let sha512 = sha512.finalize();
83
84        let mut md5 = Md5::new();
85        md5.update(contents);
86        let md5 = md5.finalize();
87
88        let lzjd_str = LzDigest::from(contents).to_string();
89
90        let mut builder = TlshBuilder::new(
91            tlsh_fixed::BucketKind::Bucket256,
92            tlsh_fixed::ChecksumKind::ThreeByte,
93            tlsh_fixed::Version::Version4,
94        );
95
96        builder.update(contents);
97
98        let tlsh = if let Ok(hasher) = builder.build() {
99            Some(hasher.hash())
100        } else {
101            None
102        };
103
104        // This won't panic since the MD5 hash is 16 bytes long
105        let md5 = Uuid::from_bytes(uuid::Bytes::from(md5));
106
107        let file_command = {
108            if let Ok(cookie) = magic::Cookie::open(magic::cookie::Flags::ERROR) {
109                let db_paths = DatabasePaths::default();
110                if let Ok(cookie) = cookie.load(&db_paths) {
111                    if let Ok(output) = cookie.buffer(contents) {
112                        output
113                    } else {
114                        error!("LibMagic: failed to get output for buffer");
115                        String::new()
116                    }
117                } else {
118                    error!("LibMagic: failed to load signature database");
119                    String::new()
120                }
121            } else {
122                error!("LibMagic: failed to get handle");
123                String::new()
124            }
125        };
126
127        Self {
128            name: name.map(str::to_ascii_lowercase),
129            size: contents.len() as u64,
130            entropy: contents.entropy(),
131            sha1: sha1.to_vec(),
132            sha256: sha256.to_vec(),
133            sha384: sha384.to_vec(),
134            sha512: sha512.to_vec(),
135            md5,
136            lzjd: Some(lzjd_str),
137            ssdeep: Some(FuzzyHash::new(contents).to_string()),
138            tlsh,
139            humanhash: humanize(&md5, 4),
140            file_command,
141        }
142    }
143}
144
145/// File Types known to Malware DB; a magic number has to be matched to a database ID.
146#[derive(Debug, Clone)]
147pub struct FileType {
148    /// Database ID number
149    pub id: u32,
150
151    /// Friendly name
152    pub name: String,
153
154    /// Description of the type
155    pub description: Option<String>,
156
157    /// Magic numbers as bytes
158    /// These are the first few bytes of the file which identify it's type
159    /// Some types have more than one possible magic number, though it's rare
160    pub magic: Vec<Vec<u8>>,
161
162    /// Whether or not this file is executable on some system
163    /// Assumption: if not executable, it's a document
164    pub executable: bool,
165}
166
167/// File types, just simple Vec wrapper around [`FileType`].
168pub struct FileTypes(pub Vec<FileType>);
169
170impl From<FileType> for SupportedFileType {
171    fn from(value: FileType) -> Self {
172        Self {
173            name: value.name,
174            magic: value.magic.iter().map(hex::encode).collect(),
175            is_executable: value.executable,
176            description: value.description,
177        }
178    }
179}
180
181impl From<FileTypes> for SupportedFileTypes {
182    fn from(value: FileTypes) -> Self {
183        Self {
184            types: value.0.into_iter().map(std::convert::Into::into).collect(),
185            message: None,
186        }
187    }
188}
189
190#[cfg(test)]
191mod test {
192    use super::*;
193    use std::str::FromStr;
194
195    #[test]
196    fn meta_and_sim_hashes() {
197        let contents = include_bytes!("../../../types/testdata/elf/elf_haiku_x86").to_vec();
198        let meta = FileMetadata::new(&contents, Some("elf_haiku_x86"));
199        assert!(meta.lzjd.is_some());
200        assert!(meta.tlsh.is_some());
201        assert!(meta.ssdeep.is_some());
202
203        let ssdeep = meta.ssdeep.unwrap();
204        let tlsh = meta.tlsh.unwrap();
205        let lzjd = meta.lzjd.unwrap();
206
207        println!("LZJD: {lzjd}");
208        println!("Tlsh: {tlsh}");
209        println!("SSDeep: {ssdeep}");
210        println!("Human hash: {}", meta.humanhash);
211        println!("File command: {}", meta.file_command);
212
213        assert_eq!(FuzzyHash::compare(ssdeep.clone(), ssdeep).unwrap(), 100);
214
215        let tlsh =
216            tlsh_fixed::Tlsh::from_str(&tlsh).expect("failed to convert tlsh string to object");
217        assert_eq!(tlsh.diff(&tlsh, true), 0);
218    }
219}
malwaredb_server/db/types.rs

malwaredb_server/db/
types.rs
