#![forbid(unsafe_code)]
#![warn(missing_docs)]
#![cfg_attr(docsrs, feature(doc_cfg))]
#[cfg(feature = "cdr")]
#[cfg_attr(docsrs, doc(cfg(feature = "cdr")))]
pub mod cdr;
pub mod detect;
pub mod hashlist;
mod image;
pub mod limits;
mod payload;
mod pdf;
pub mod policy;
mod ps;
pub mod report;
mod svg;
#[cfg(feature = "yara")]
mod yara;
use std::io::{self, Read};
use sha2::{Digest, Sha256};
pub use detect::FileType;
pub use hashlist::{HashList, HashListError};
pub use limits::Limits;
use limits::{Budget, LimitExceeded};
pub use policy::{AllowError, Policy};
pub use report::{Finding, Report, Severity, Verdict};
#[cfg(feature = "yara")]
#[cfg_attr(docsrs, doc(cfg(feature = "yara")))]
pub use yara::{YaraError, YaraRules};
use payload::{PayloadKind, Scope};
#[derive(Debug, Clone, Copy, Default)]
pub struct ScanHints<'a> {
pub filename: Option<&'a str>,
pub content_type: Option<&'a str>,
}
#[derive(Debug, Clone, Default)]
pub struct Scanner {
limits: Limits,
policy: Policy,
hashlist: HashList,
without_hash: bool,
pdf_passwords: Passwords,
#[cfg(feature = "yara")]
yara: Option<YaraRules>,
}
#[derive(Clone, Default)]
struct Passwords(Vec<Vec<u8>>);
impl std::fmt::Debug for Passwords {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "Passwords({} hidden)", self.0.len())
}
}
#[derive(Debug, Clone, Default)]
pub struct ScannerBuilder {
scanner: Scanner,
}
impl ScannerBuilder {
pub fn limits(mut self, limits: Limits) -> Self {
self.scanner.limits = limits;
self
}
pub fn policy(mut self, policy: Policy) -> Self {
self.scanner.policy = policy;
self
}
pub fn without_hash(mut self) -> Self {
self.scanner.without_hash = true;
self
}
pub fn hashlist(mut self, hashlist: HashList) -> Self {
self.scanner.hashlist = hashlist;
self
}
pub fn pdf_passwords<P: Into<Vec<u8>>>(
mut self,
passwords: impl IntoIterator<Item = P>,
) -> Self {
self.scanner.pdf_passwords = Passwords(passwords.into_iter().map(Into::into).collect());
self
}
#[cfg(feature = "yara")]
pub fn yara(mut self, rules: YaraRules) -> Self {
self.scanner.yara = Some(rules);
self
}
pub fn build(self) -> Scanner {
self.scanner
}
}
const APART: usize = 4 << 20;
impl Scanner {
pub fn builder() -> ScannerBuilder {
ScannerBuilder::default()
}
pub fn limits(&self) -> &Limits {
&self.limits
}
#[cfg(feature = "cdr")]
#[cfg_attr(docsrs, doc(cfg(feature = "cdr")))]
pub fn sanitize(
&self,
data: &[u8],
hints: ScanHints<'_>,
options: &cdr::Options,
) -> Result<cdr::Sanitized, cdr::Error> {
let report = self.scan_bytes(data, hints);
if report.verdict != Verdict::Clean {
return Err(cdr::Error::Rejected(Box::new(report)));
}
let image = cdr::rebuild_with(data, &self.limits, options, &self.pdf_passwords.0)?;
let rebuilt = self.scan_bytes(&image.data, ScanHints::default());
if rebuilt.verdict != Verdict::Clean {
return Err(cdr::Error::Unclean(Box::new(rebuilt)));
}
Ok(cdr::Sanitized { report, image })
}
pub fn scan_reader(&self, reader: impl Read, hints: ScanHints<'_>) -> io::Result<Report> {
let mut data = Vec::new();
reader
.take(self.limits.max_file_size.saturating_add(1))
.read_to_end(&mut data)?;
Ok(self.scan_bytes(&data, hints))
}
pub fn scan_bytes(&self, data: &[u8], hints: ScanHints<'_>) -> Report {
let mut findings = Vec::new();
let size = data.len() as u64;
let hash = || -> [u8; 32] { Sha256::digest(data).into() };
let wanted = !self.without_hash || !self.hashlist.is_empty();
let (digest, (detected, declared_types)) = if !wanted {
(None, self.analyze(data, hints, &mut findings))
} else if data.len() < APART {
(Some(hash()), self.analyze(data, hints, &mut findings))
} else {
std::thread::scope(|scope| {
let hashing = std::thread::Builder::new().spawn_scoped(scope, hash);
let analysis = self.analyze(data, hints, &mut findings);
let digest = hashing
.ok()
.and_then(|thread| thread.join().ok())
.unwrap_or_else(hash);
(Some(digest), analysis)
})
};
if digest.is_some_and(|digest| self.hashlist.contains(&digest)) {
findings.insert(
0,
Finding::new(
"hash.blocklisted",
Severity::Critical,
"SHA-256 is on the blocklist",
),
);
}
let verdict = self.policy.apply(&mut findings);
Report {
verdict,
detected_type: detected,
declared_types,
size,
sha256: digest
.as_ref()
.map(|digest| to_hex(digest))
.unwrap_or_default(),
findings,
}
}
fn analyze(
&self,
data: &[u8],
hints: ScanHints<'_>,
findings: &mut Vec<Finding>,
) -> (FileType, Vec<FileType>) {
let data = if data.len() as u64 > self.limits.max_file_size {
findings.push(Finding::new(
"limit.size",
Severity::Medium,
format!(
"file exceeds the {} byte limit; only the start was analyzed",
self.limits.max_file_size
),
));
&data[..self.limits.max_file_size as usize]
} else {
data
};
let mut budget = Budget::new(&self.limits);
let mut detected = detect::detect(data);
let mut inflated = None;
if detected == FileType::Gzip {
match svg::gunzip(data, self.limits.max_file_size, &mut budget) {
Ok(inner) if detect::detect(&inner) == FileType::Svg => {
detected = FileType::Svg;
inflated = Some(inner);
}
Ok(_) | Err(svg::GunzipError::Corrupt) => {}
Err(svg::GunzipError::Limit) => {
findings.push(LimitExceeded::Decompression.finding())
}
}
}
let data = inflated.as_deref().unwrap_or(data);
let declared_types = self.check_claims(detected, hints, findings);
self.check_type(detected, findings);
self.analyze_content(data, detected, &mut budget, findings);
if detected == FileType::Unknown && declared_types.contains(&FileType::PostScript) {
ps::analyze(data, &self.limits, &mut budget, findings);
}
#[cfg(feature = "yara")]
if let Some(rules) = &self.yara {
rules.scan(data, self.limits.max_duration, findings);
}
(detected, declared_types)
}
fn analyze_content(
&self,
data: &[u8],
detected: FileType,
budget: &mut Budget,
findings: &mut Vec<Finding>,
) {
if data.len() < APART {
check_payloads(data, detected, findings);
return self.analyze_format(data, detected, budget, findings);
}
let search = || {
let mut found = Vec::new();
check_payloads(data, detected, &mut found);
found
};
std::thread::scope(|scope| {
let searching = std::thread::Builder::new().spawn_scoped(scope, search);
let before = findings.len();
self.analyze_format(data, detected, budget, findings);
let found = searching
.ok()
.and_then(|thread| thread.join().ok())
.unwrap_or_else(search);
findings.splice(before..before, found);
});
}
fn analyze_format(
&self,
data: &[u8],
detected: FileType,
budget: &mut Budget,
findings: &mut Vec<Finding>,
) {
match detected {
FileType::Svg => svg::analyze(data, budget, findings),
FileType::Pdf => {
let mut nested =
|inner: &[u8], budget: &mut Budget, findings: &mut Vec<Finding>| {
self.scan_embedded(inner, budget, findings)
};
pdf::analyze(
data,
budget,
findings,
&self.pdf_passwords.0,
self.limits.max_pixels,
&mut nested,
);
}
FileType::PostScript => ps::analyze(data, &self.limits, budget, findings),
_ => image::analyze(data, detected, &self.limits, budget, findings),
}
}
fn scan_embedded(&self, data: &[u8], budget: &mut Budget, findings: &mut Vec<Finding>) {
let detected = detect::detect(data);
if detected.is_executable() {
findings.push(Finding::new(
"type.executable",
Severity::Critical,
format!("content is an executable ({})", detected.as_str()),
));
}
self.analyze_content(data, detected, budget, findings);
#[cfg(feature = "yara")]
if let Some(rules) = &self.yara {
rules.scan(data, self.limits.max_duration, findings);
}
}
fn check_claims(
&self,
detected: FileType,
hints: ScanHints<'_>,
findings: &mut Vec<Finding>,
) -> Vec<FileType> {
let mut declared = Vec::new();
let mut check = |source: &str, claim: &str, types: Option<&'static [FileType]>| {
let Some(types) = types else { return };
for &file_type in types {
if !declared.contains(&file_type) {
declared.push(file_type);
}
}
if !types.contains(&detected) {
findings.push(Finding::new(
"type.mismatch",
Severity::Medium,
format!(
"{source} {claim:?} does not match {} content",
detected.as_str()
),
));
}
};
if let Some(ext) = hints.filename.and_then(detect::extension) {
check("extension", ext, detect::types_for_extension(ext));
}
if let Some(content_type) = hints.content_type {
check(
"Content-Type",
content_type,
detect::types_for_mime(content_type),
);
}
if let Some(ext) = hints.filename.and_then(detect::dangerous_extension) {
findings.push(Finding::new(
"name.dangerous_extension",
Severity::High,
format!("filename contains the executable extension {ext:?}"),
));
}
declared
}
fn check_type(&self, detected: FileType, findings: &mut Vec<Finding>) {
if detected.is_executable() {
findings.push(Finding::new(
"type.executable",
Severity::Critical,
format!("content is an executable ({})", detected.as_str()),
));
} else if detected == FileType::Unknown {
findings.push(Finding::new(
"type.unknown",
Severity::Medium,
"content type could not be identified",
));
} else if !self.policy.is_allowed(detected) {
findings.push(Finding::new(
"type.not_allowed",
Severity::Medium,
format!("{} files are not accepted by policy", detected.as_str()),
));
}
}
}
fn check_payloads(data: &[u8], detected: FileType, findings: &mut Vec<Finding>) {
let scope = if detected.is_raster_image() {
Scope::Binary
} else {
Scope::Mixed
};
for hit in payload::scan(data, scope) {
let (code, message) = match hit.kind {
PayloadKind::Php => ("payload.php", "PHP opening tag in file content"),
PayloadKind::Script => (
"payload.script",
"browser-executable markup inside an image",
),
PayloadKind::Template => ("payload.template", "ASP/JSP template tag inside an image"),
};
findings.push(Finding::new(code, Severity::High, message).at(hit.offset));
}
}
fn to_hex(bytes: &[u8]) -> String {
const DIGITS: &[u8; 16] = b"0123456789abcdef";
let mut hex = String::with_capacity(bytes.len() * 2);
for &byte in bytes {
hex.push(DIGITS[(byte >> 4) as usize] as char);
hex.push(DIGITS[(byte & 0xF) as usize] as char);
}
hex
}