malwaredb_api/

lib.rs

#![doc = include_str!("../README.md")]
#![deny(missing_docs)]

/// Wrapper for fixed-size hash digests from hex strings
pub mod digest;

use std::fmt::{Display, Formatter};

use chrono::serde::ts_seconds_option;
use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use zeroize::{Zeroize, ZeroizeOnDrop};

/// MDB version
pub const MDB_VERSION: &str = env!("CARGO_PKG_VERSION");

/// Header key used to present the API key to the server
pub const MDB_API_HEADER: &str = "mdb-api-key";

/// Login API endpoint, POST
pub const USER_LOGIN_URL: &str = "/v1/users/getkey";

/// User logs in with username and password
#[derive(Deserialize, Serialize, Zeroize, ZeroizeOnDrop)]
pub struct GetAPIKeyRequest {
    /// Username
    pub user: String,

    /// User's password
    pub password: String,
}

/// Logout API endpoint, GET, authenticated.
pub const USER_LOGOUT_URL: &str = "/v1/users/clearkey";

/// Response includes the key, if the credentials were correct,
/// and possibly show a message related to errors or warnings.
#[derive(Deserialize, Serialize, Zeroize, ZeroizeOnDrop)]
pub struct GetAPIKeyResponse {
    /// User's API key if successful
    pub key: Option<String>,

    /// Error response
    pub message: Option<String>,
}

/// User's get self information API endpoint, GET, authenticated
/// User `EmptyAuthenticatingPost` to authenticate
pub const USER_INFO_URL: &str = "/v1/users/info";

/// User gets information about their account
#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct GetUserInfoResponse {
    /// User's numeric ID
    pub id: i32,

    /// User's name
    pub username: String,

    /// User's group memberships, if any
    pub groups: Vec<String>,

    /// User's available sample sources, if any
    pub sources: Vec<String>,

    /// If the user is an admin
    pub is_admin: bool,
}

/// Server information, request is empty, GET, Unauthenticated.
pub const SERVER_INFO: &str = "/v1/server/info";

/// Information about the server
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
pub struct ServerInfo {
    /// Operating System used
    pub os_name: String,

    /// Memory footprint
    pub memory_used: String,

    /// MDB version
    pub mdb_version: String,

    /// Type and version of the database
    pub db_version: String,

    /// Size of the database on disk
    pub db_size: String,

    /// Total number of samples in MalwareDB
    pub num_samples: u64,

    /// Total users of MalwareDB
    pub num_users: u32,

    /// Uptime of MalwareDB in a human readable format
    pub uptime: String,
}

/// File types supported by MalwareDB, request is empty, GET, Unauthenticated.
pub const SUPPORTED_FILE_TYPES: &str = "/v1/server/types";

/// One record of supported file types
#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct SupportedFileType {
    /// Common name of the file type
    pub name: String,

    /// Magic number bytes in hex of the file type
    pub magic: Vec<String>,

    /// Whether the file type is executable
    pub is_executable: bool,

    /// Description of the file type
    pub description: Option<String>,
}

/// Server's supported types, the response
#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct SupportedFileTypes {
    /// Supported file types
    pub types: Vec<SupportedFileType>,

    /// Optional server messages
    pub message: Option<String>,
}

/// Endpoint for the sources, per-user, GET, authenticated
pub const LIST_SOURCES: &str = "/v1/sources/list";

/// Source record
#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct SourceInfo {
    /// ID of the source
    pub id: u32,

    /// Name of the source
    pub name: String,

    /// Description of the source
    pub description: Option<String>,

    /// URL of the source, or where the files were found
    pub url: Option<String>,

    /// Creation date or first acquisition date of or from the source
    pub first_acquisition: DateTime<Utc>,

    /// Whether the source holds malware
    pub malicious: Option<bool>,
}

/// Sources response for request for sources
#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct Sources {
    /// List of sources
    pub sources: Vec<SourceInfo>,

    /// Error message, if any
    pub message: Option<String>,
}

/// API endpoint for uploading a sample, POST, Authenticated
pub const UPLOAD_SAMPLE: &str = "/v1/samples/upload";

/// New file sample being sent to MalwareDB
#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct NewSample {
    /// The original file name, might not be known
    pub file_name: String,

    /// ID of the source for this sample
    pub source_id: u32,

    /// Base64 encoding of the binary file
    pub file_contents_b64: String,

    /// SHA-256 of the sample being sent, for server-side validation
    pub sha256: String,
}

/// API endpoint for downloading a sample, GET. The hash value goes at the end of the URL.
/// For example: /v1/samples/download/aabbccddeeff0011223344556677889900
/// Response is raw bytes of the file, or HTTP 404 if not found
pub const DOWNLOAD_SAMPLE: &str = "/v1/samples/download";

/// API endpoint for downloading a sample as a CaRT file, GET
/// For example: /v1/samples/download/cart/aabbccddeeff0011223344556677889900
/// Response is the file encoded in a CaRT container file, or HTTP 404 if not found
pub const DOWNLOAD_SAMPLE_CART: &str = "/v1/samples/download/cart";

/// API endpoint to get a report for a given sample
/// For example: /v1/samples/report/aabbccddeeff0011223344556677889900
pub const SAMPLE_REPORT: &str = "/v1/samples/report";

/// VirusTotal hits summary
#[derive(Clone, Debug, Default, PartialEq, Deserialize, Serialize)]
pub struct VirusTotalSummary {
    /// Anti-Virus products which identified the sample as malicious
    pub hits: u32,

    /// Anti-Virus products available when last analyzed
    pub total: u32,

    /// Hit details in json format, if available
    #[serde(default)]
    pub detail: Option<serde_json::Value>,

    /// Date of most recent analysis
    #[serde(default, with = "ts_seconds_option")]
    pub last_analysis_date: Option<DateTime<Utc>>,
}

// TODO: Add sections for parsed fields for documents, executables
/// All the data for a sample known to MalwareDB
#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
pub struct Report {
    ///MD5 hash
    pub md5: String,

    /// SHA-1 hash
    pub sha1: String,

    /// SHA-256 hash
    pub sha256: String,

    /// SHA-384 hash
    pub sha384: String,

    /// SHA-512 hash
    pub sha512: String,

    /// LZJD similarity hash, if available
    /// <https://github.com/EdwardRaff/LZJD>
    pub lzjd: Option<String>,

    /// TLSH similarity hash, if available
    /// <https://github.com/trendmicro/tlsh>
    pub tlsh: Option<String>,

    /// SSDeep similarity hash, if available
    /// <https://ssdeep-project.github.io/ssdeep/index.html>
    pub ssdeep: Option<String>,

    /// Human hash
    /// <https://github.com/zacharyvoase/humanhash>
    pub humanhash: Option<String>,

    /// The output from libmagic, aka the `file` command
    /// <https://man7.org/linux/man-pages/man3/libmagic.3.html>
    pub filecommand: Option<String>,

    /// Sample size in bytes
    pub bytes: u32,

    /// Sample size in human-readable size (2048 becomes 2 kb, for example)
    pub size: String,

    /// Entropy of the file, values over 6.5 may indicate compression or encryption
    pub entropy: f32,

    /// VirusTotal summary data, if enabled on the server
    /// <https://www.virustotal.com>
    #[serde(default)]
    pub vt: Option<VirusTotalSummary>,
}

impl Display for Report {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        writeln!(f, "Size: {} bytes, or {}", self.bytes, self.size)?;
        writeln!(f, "Entropy: {}", self.entropy)?;
        if let Some(filecmd) = &self.filecommand {
            writeln!(f, "File command: {filecmd}")?;
        }
        if let Some(vt) = &self.vt {
            writeln!(f, "VT Hits: {}/{}", vt.hits, vt.total)?;
        }
        writeln!(f, "MD5: {}", self.md5)?;
        writeln!(f, "SHA-1: {}", self.sha1)?;
        writeln!(f, "SHA256: {}", self.sha256)
    }
}

/// API endpoint for finding samples which are similar to specific file, POST, Authenticated.
pub const SIMILAR_SAMPLES: &str = "/v1/samples/similar";

/// The hash by which a sample is identified
#[derive(Clone, Copy, Debug, Eq, PartialEq, Deserialize, Serialize)]
#[non_exhaustive]
pub enum SimilarityHashType {
    /// SSDeep similarity of the whole file
    SSDeep,

    /// LZJD similarity of the whole file
    LZJD,

    /// TLSH similarity of the hole file
    TLSH,

    /// PEHash, for PE32 files
    PEHash,

    /// Import Hash for executable files
    ImportHash,

    /// SSDeep fuzzy hash of the import data, for executable files
    FuzzyImportHash,
}

impl SimilarityHashType {
    /// For a similarity hash type, return:
    /// * The database table & field which stores the hash
    /// * If applicable, the similarity hash function (Postgres extension) which calculates the similarity
    pub fn get_table_field_simfunc(&self) -> (&'static str, Option<&'static str>) {
        match self {
            SimilarityHashType::SSDeep => ("file.ssdeep", Some("fuzzy_hash_compare")),
            SimilarityHashType::LZJD => ("file.lzjd", Some("lzjd_compare")),
            SimilarityHashType::TLSH => ("file.tlsh", Some("tlsh_compare")),
            SimilarityHashType::PEHash => ("executable.pehash", None),
            SimilarityHashType::ImportHash => ("executable.importhash", None),
            SimilarityHashType::FuzzyImportHash => {
                ("executable.importhashfuzzy", Some("fuzzy_hash_compare"))
            }
        }
    }
}

impl Display for SimilarityHashType {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        match self {
            SimilarityHashType::SSDeep => write!(f, "SSDeep"),
            SimilarityHashType::LZJD => write!(f, "LZJD"),
            SimilarityHashType::TLSH => write!(f, "TLSH"),
            SimilarityHashType::PEHash => write!(f, "PeHash"),
            SimilarityHashType::ImportHash => write!(f, "Import Hash (IMPHASH)"),
            SimilarityHashType::FuzzyImportHash => write!(f, "Fuzzy Import hash"),
        }
    }
}

/// Requesting a sample from MalwareDB by similarity hash
#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct SimilarSamplesRequest {
    /// The hashes of the requested sample
    pub hashes: Vec<(SimilarityHashType, String)>,
}

/// Relation between a similar sample and the hashes by which the sample is similar
#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct SimilarSample {
    /// The SHA-256 hash of the found sample
    pub sha256: String,

    /// Matches from the requested sample to this sample by algorithm and score
    pub algorithms: Vec<(SimilarityHashType, f32)>,
}

/// Response indicating samples which are similar
#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct SimilarSamplesResponse {
    /// The responses
    pub results: Vec<SimilarSample>,

    /// Possible messages from the server, if any
    pub message: Option<String>,
}

/// API endpoint for finding samples which are similar to specific file, POST
pub const LIST_LABELS: &str = "/v1/labels";

/// A label, used for sources and samples
#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct Label {
    /// Label ID
    pub id: u64,

    /// Label value
    pub name: String,

    /// Label parent
    pub parent: Option<String>,
}

/// One or more labels
#[derive(Clone, Debug, Default, Deserialize, Serialize)]
pub struct Labels(pub Vec<Label>);

// Convenience functions
impl Labels {
    /// Number of labels
    pub fn len(&self) -> usize {
        self.0.len()
    }

    /// If the labels are empty
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }
}

impl Display for Labels {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        if self.is_empty() {
            return writeln!(f, "No labels.");
        }
        for label in &self.0 {
            let parent = if let Some(parent) = &label.parent {
                format!(", parent: {parent}")
            } else {
                String::new()
            };
            writeln!(f, "{}: {}{parent}", label.id, label.name)?;
        }
        Ok(())
    }
}