malwaredb-api 0.3.3

// SPDX-License-Identifier: Apache-2.0

#![doc = include_str!("../README.md")]
#![deny(missing_docs)]
#![deny(clippy::all)]
#![deny(clippy::pedantic)]
#![forbid(unsafe_code)]

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

use crate::digest::HashType;

use std::collections::HashMap;
use std::error::Error;
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");

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

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

/// Endpoint name for use with Multicast DNS
pub const MDNS_NAME: &str = "_malwaredb._tcp.local.";

/// User authentication with username and password to get the API key
#[derive(Deserialize, Serialize, Zeroize, ZeroizeOnDrop)]
pub struct GetAPIKeyRequest {
    /// Username
    pub user: String,

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

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

/// Respond to authentication with 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: String,

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

/// For request types, wrap in this struct to handle some error conditions
///
/// All API endpoints use this response format EXCEPT:
///   * [`USER_LOGOUT_URL`]
///   * [`UPLOAD_SAMPLE_JSON_URL`]
///   * [`UPLOAD_SAMPLE_CBOR_URL`]
///   * [`DOWNLOAD_SAMPLE_URL`]
///   * [`DOWNLOAD_SAMPLE_CART_URL`]
#[derive(Clone, Debug, Deserialize, Serialize)]
pub enum ServerResponse<D> {
    /// Request successful
    #[serde(alias = "success")]
    Success(D),

    /// Request unsuccessful
    #[serde(alias = "error")]
    Error(ServerError),
}

impl<D> ServerResponse<D> {
    /// Unwrap a server response
    ///
    /// # Panics
    ///
    /// Will panic if the response is an error
    #[inline]
    pub fn unwrap(self) -> D {
        match self {
            ServerResponse::Success(d) => d,
            ServerResponse::Error(e) => panic!("forced ServerResponse::unwrap() on error: {e}"),
        }
    }

    /// Convert the server response into a traditional [`Result`] type
    ///
    /// # Errors
    ///
    /// The return error is the server error, if present
    #[inline]
    pub fn into_result(self) -> Result<D, ServerError> {
        match self {
            ServerResponse::Success(d) => Ok(d),
            ServerResponse::Error(e) => Err(e),
        }
    }

    /// If the server response was successful
    #[inline]
    pub const fn is_successful(&self) -> bool {
        matches!(*self, ServerResponse::Success(_))
    }

    /// If the server response was not successful
    #[inline]
    pub const fn is_err(&self) -> bool {
        matches!(*self, ServerResponse::Error(_))
    }
}

/// Server error responses
#[derive(Copy, Clone, Debug, Deserialize, Serialize, PartialEq, Eq, Hash)]
pub enum ServerError {
    /// The server was asked for samples but doesn't store them
    NoSamples,

    /// The requested item was not found or the search yielded no results
    NotFound,

    /// Internal server error, details not disclosed to the client
    ServerError,

    /// Unauthorized: API key was not provided, or the user doesn't have access to the requested item(s)
    Unauthorized,

    /// Request was for a feature which is not supported by the server, such as Yara for example
    Unsupported,
}

impl Display for ServerError {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        match self {
            ServerError::NoSamples => write!(f, "NoSamples"),
            ServerError::NotFound => write!(f, "NotFound"),
            ServerError::ServerError => write!(f, "ServerError"),
            ServerError::Unauthorized => write!(f, "Unauthorized"),
            ServerError::Unsupported => write!(f, "Unsupported"),
        }
    }
}

impl Error for ServerError {}

/// User's account information API endpoint, GET, authenticated
pub const USER_INFO_URL: &str = "/v1/users/info";

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

    /// 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,

    /// When the account was created
    pub created: DateTime<Utc>,

    /// User has read-only access, perhaps a guest or demo account
    pub is_readonly: bool,
}

/// Server information, request is empty, GET, Unauthenticated.
pub const SERVER_INFO_URL: &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: semver::Version,

    /// 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 Malware DB
    pub num_samples: u64,

    /// Total users of Malware DB
    pub num_users: u32,

    /// Uptime of Malware DB in a human-readable format
    pub uptime: String,

    /// The name of the Malware DB instance
    pub instance_name: String,
}

/// File types supported by Malware DB, request is empty, GET, Unauthenticated.
pub const SUPPORTED_FILE_TYPES_URL: &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_URL: &str = "/v1/sources/list";

/// Information about a sample source
#[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 with JSON, POST, Authenticated
pub const UPLOAD_SAMPLE_JSON_URL: &str = "/v1/samples/json/upload";

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

/// New file sample being sent to Malware DB via [`UPLOAD_SAMPLE_JSON_URL`]
#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct NewSampleB64 {
    /// The original file name, which might not be known. If it's not known,
    /// use a hash or something like "unknown.bin".
    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,
}

/// New file sample being sent to Malware DB via [`UPLOAD_SAMPLE_CBOR_URL`]
#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct NewSampleBytes {
    /// The original file name, which might not be known. If it's not known,
    /// use a hash or something like "unknown.bin".
    pub file_name: String,

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

    /// Raw binary contents
    pub file_contents: Vec<u8>,

    /// 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.
/// Example: `/v1/samples/download/aabbccddeeff0011223344556677889900`
/// Response is raw bytes of the file, or HTTP 404 if not found
pub const DOWNLOAD_SAMPLE_URL: &str = "/v1/samples/download";

/// API endpoint for downloading a sample as a `CaRT` container file, GET
/// 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_URL: &str = "/v1/samples/download/cart";

/// API endpoint to get a report for a given sample
/// Example: `/v1/samples/report/aabbccddeeff0011223344556677889900`
pub const SAMPLE_REPORT_URL: &str = "/v1/samples/report";

/// Virus Total hits summary for a specific sample
#[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>,

    /// Most recent analysis date, if available
    #[serde(default, with = "ts_seconds_option")]
    pub last_analysis_date: Option<DateTime<Utc>>,
}

// TODO: Add sections for parsed fields for documents, executables
/// Information for an individual sample
#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
pub struct Report {
    /// MD-5 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: u64,

    /// 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,

    /// Virus Total 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 a specific file, POST, Authenticated.
pub const SIMILAR_SAMPLES_URL: &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 and field which stores the hash
    /// * If applicable, the similarity hash function which calculates the similarity
    #[must_use]
    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 hashes of possible similar samples 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>,
}

/// APU endpoint for searching for files with some criteria
pub const SEARCH_URL: &str = "/v1/search";

/// Searching the next batch from a prior search, or the initial search
#[derive(Clone, Debug, Deserialize, Serialize, Eq, PartialEq)]
pub enum SearchType {
    /// The next batch of results from a prior search
    Continuation(uuid::Uuid),

    /// The initial search
    Search(SearchRequestParameters),
}

/// Search for a file by some criteria, all of which are an AND operation:
/// * Partial hash
/// * Name of the sample
/// * Type of the sample
/// * Libmagic description of the sample
/// * Labels applied to the sample
#[derive(Clone, Debug, Deserialize, Serialize, Eq, PartialEq)]
pub struct SearchRequestParameters {
    /// Search for a file by partial hash
    pub partial_hash: Option<(PartialHashSearchType, String)>,

    /// Search for a file by whole or partial file name
    pub file_name: Option<String>,

    /// Maximum number of results to return, 100 results or fewer.
    pub limit: u32,

    /// Optionally search for samples of a specific file type.
    pub file_type: Option<String>,

    /// Optionally search for samples based on `libmagic`, also known as the file command.
    pub magic: Option<String>,

    /// Optionally search for samples with specific label(s).
    pub labels: Option<Vec<String>>,

    /// Get the returned result by a hash type.
    /// [`PartialHashSearchType::Any`] results in SHA-256
    pub response: PartialHashSearchType,
}

impl SearchRequestParameters {
    /// Ensure the search request is valid:
    /// * The partial hash is valid hexidecimal, if present
    /// * At least one search parameter is provided
    /// * The limit must be greater than zero
    #[must_use]
    #[inline]
    pub fn is_valid(&self) -> bool {
        if self.limit == 0 {
            return false;
        }

        if let Some((_hash_type, partial_hash)) = &self.partial_hash {
            let hex = hex::decode(partial_hash);
            return hex.is_ok();
        }

        self.partial_hash.is_some()
            || self.file_name.is_some()
            || self.file_type.is_some()
            || self.magic.is_some()
            || self.labels.is_some()
    }
}

/// This trait implementation is provided as a convenience. This does not create a valid object.
impl Default for SearchRequestParameters {
    fn default() -> Self {
        Self {
            partial_hash: None,
            file_name: None,
            limit: 100,
            labels: None,
            file_type: None,
            magic: None,
            response: PartialHashSearchType::default(),
        }
    }
}

/// Search for a file by some criteria
/// Specifying both a hash and file name is an AND operation!
#[derive(Clone, Debug, Deserialize, Serialize, Eq, PartialEq)]
pub struct SearchRequest {
    /// Search or continuation of a search
    pub search: SearchType,
}

impl SearchRequest {
    /// Ensure the search request is valid:
    /// * The partial hash is valid hexidecimal
    /// * At least a file path or partial hash is provided
    #[must_use]
    #[inline]
    pub fn is_valid(&self) -> bool {
        if let SearchType::Search(search) = &self.search {
            search.is_valid()
        } else {
            true
        }
    }
}

/// Search result
#[derive(Clone, Debug, Deserialize, Serialize, Eq, PartialEq)]
pub struct SearchResponse {
    /// Hashes of samples which match the search criteria
    pub hashes: Vec<String>,

    /// Identifier for getting the next batch of results
    pub pagination: Option<uuid::Uuid>,

    /// The total number of samples which match the search criteria
    pub total_results: u64,

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

/// Specify the type of hash when searching for a partial match
#[derive(Clone, Debug, Default, Deserialize, Serialize, Eq, PartialEq)]
pub enum PartialHashSearchType {
    /// Search by any known hash type
    Any,

    /// Search only for MD5 hashes
    MD5,

    /// Search only for SHA-1 hashes
    SHA1,

    /// Search only for SHA-256 hashes
    #[default]
    SHA256,

    /// Search only for SHA-384 hashes
    SHA384,

    /// Search only for SHA-512 hashes
    SHA512,
}

impl Display for PartialHashSearchType {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        match self {
            PartialHashSearchType::Any => write!(f, "any"),
            PartialHashSearchType::MD5 => write!(f, "md5"),
            PartialHashSearchType::SHA1 => write!(f, "sha1"),
            PartialHashSearchType::SHA256 => write!(f, "sha256"),
            PartialHashSearchType::SHA384 => write!(f, "sha384"),
            PartialHashSearchType::SHA512 => write!(f, "sha512"),
        }
    }
}

impl TryInto<PartialHashSearchType> for &str {
    type Error = String;

    fn try_into(self) -> Result<PartialHashSearchType, Self::Error> {
        match self {
            "any" => Ok(PartialHashSearchType::Any),
            "md5" => Ok(PartialHashSearchType::MD5),
            "sha1" => Ok(PartialHashSearchType::SHA1),
            "sha256" => Ok(PartialHashSearchType::SHA256),
            "sha384" => Ok(PartialHashSearchType::SHA384),
            "sha512" => Ok(PartialHashSearchType::SHA512),
            x => Err(format!("Invalid hash type {x}")),
        }
    }
}

impl TryInto<PartialHashSearchType> for Option<&str> {
    type Error = String;

    fn try_into(self) -> Result<PartialHashSearchType, Self::Error> {
        if let Some(hash) = self {
            hash.try_into()
        } else {
            Ok(PartialHashSearchType::SHA256)
        }
    }
}

/// API endpoint for searching for samples using YARA rules.
/// * POST: submit the search request
/// * GET: get the search results or check on status
pub const YARA_SEARCH_URL: &str = "/v1/yara";

/// Search for samples using YARA
#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct YaraSearchRequest {
    /// The Yara rules
    pub rules: Vec<String>,

    /// Get the returned result by a hash type.
    /// [`PartialHashSearchType::Any`] results in SHA-256
    pub response: PartialHashSearchType,
}

/// Provide the client the UUID of the search request.
#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct YaraSearchRequestResponse {
    /// UUID response
    pub uuid: uuid::Uuid,
}

/// Search result from Yara
#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct YaraSearchResponse {
    /// Vector of pairs of hash and Yara search name
    pub results: HashMap<String, Vec<HashType>>,
}

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

/// A label, used for describing sources and/or 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 available labels
#[derive(Clone, Debug, Default, Deserialize, Serialize)]
pub struct Labels(pub Vec<Label>);

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

    /// If the labels are empty
    #[must_use]
    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(())
    }
}