use crate::{
Certainty, Finding, FindingCode, Network, Outcome,
dns::{ResolveError, TextRecords},
};
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
#[non_exhaustive]
pub enum RecordStatus {
Present,
Absent,
Invalid,
Unavailable,
}
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct DomainPosture {
spf: RecordStatus,
dmarc: RecordStatus,
mta_sts: RecordStatus,
tls_rpt: RecordStatus,
}
impl DomainPosture {
pub(crate) const fn unavailable() -> Self {
Self {
spf: RecordStatus::Unavailable,
dmarc: RecordStatus::Unavailable,
mta_sts: RecordStatus::Unavailable,
tls_rpt: RecordStatus::Unavailable,
}
}
#[must_use]
pub const fn spf(self) -> RecordStatus {
self.spf
}
#[must_use]
pub const fn dmarc(self) -> RecordStatus {
self.dmarc
}
#[must_use]
pub const fn mta_sts(self) -> RecordStatus {
self.mta_sts
}
#[must_use]
pub const fn tls_rpt(self) -> RecordStatus {
self.tls_rpt
}
}
pub(crate) async fn inspect(
network: &Network,
domain: &str,
timeout: std::time::Duration,
) -> DomainPosture {
let dmarc_name = format!("_dmarc.{domain}");
let mta_sts_name = format!("_mta-sts.{domain}");
let tls_rpt_name = format!("_smtp._tls.{domain}");
let (spf, dmarc, mta_sts, tls_rpt) = futures_util::join!(
resolve_text(network, domain, timeout),
resolve_text(network, &dmarc_name, timeout),
resolve_text(network, &mta_sts_name, timeout),
resolve_text(network, &tls_rpt_name, timeout),
);
DomainPosture {
spf: record(spf, "v=spf1"),
dmarc: record(dmarc, "v=dmarc1"),
mta_sts: record(mta_sts, "v=stsv1"),
tls_rpt: record(tls_rpt, "v=tlsrptv1"),
}
}
async fn resolve_text(
network: &Network,
domain: &str,
duration: std::time::Duration,
) -> Result<TextRecords, ResolveError> {
crate::runtime::timeout(
network.timer(),
duration,
network.resolver().resolve_text(domain),
)
.await
.unwrap_or_else(|_| {
Err(ResolveError::new(
crate::dns::ResolveErrorKind::Timeout,
"TXT lookup exceeded its deadline",
))
})
}
pub(crate) fn findings(posture: DomainPosture) -> impl Iterator<Item = Finding> {
[
posture_finding(FindingCode::PostureSpf, "SPF", posture.spf),
posture_finding(FindingCode::PostureDmarc, "DMARC", posture.dmarc),
posture_finding(FindingCode::PostureMtaSts, "MTA-STS", posture.mta_sts),
posture_finding(FindingCode::PostureTlsRpt, "TLS-RPT", posture.tls_rpt),
]
.into_iter()
.flatten()
}
fn record(result: Result<TextRecords, ResolveError>, prefix: &str) -> RecordStatus {
let Ok(records) = result else {
return RecordStatus::Unavailable;
};
let matching = records
.values()
.iter()
.filter(|value| has_version(value, prefix))
.count();
match matching {
0 => RecordStatus::Absent,
1 => RecordStatus::Present,
_ => RecordStatus::Invalid,
}
}
fn has_version(value: &str, version: &str) -> bool {
let Some((candidate, suffix)) = value.split_at_checked(version.len()) else {
return false;
};
candidate.eq_ignore_ascii_case(version)
&& (suffix.is_empty()
|| suffix
.as_bytes()
.first()
.is_some_and(|byte| matches!(byte, b' ' | b'\t' | b';')))
}
fn posture_finding(code: FindingCode, name: &'static str, status: RecordStatus) -> Option<Finding> {
match (name, status) {
(_, RecordStatus::Absent | RecordStatus::Unavailable) => None,
("SPF", RecordStatus::Present) => Some(Finding::new(
code,
Outcome::Pass,
Certainty::Conclusive,
"the domain publishes an SPF record",
)),
("DMARC", RecordStatus::Present) => Some(Finding::new(
code,
Outcome::Pass,
Certainty::Conclusive,
"the domain publishes a DMARC record",
)),
("MTA-STS", RecordStatus::Present) => Some(Finding::new(
code,
Outcome::Pass,
Certainty::Conclusive,
"the domain publishes an MTA-STS record",
)),
("TLS-RPT", RecordStatus::Present) => Some(Finding::new(
code,
Outcome::Pass,
Certainty::Conclusive,
"the domain publishes an SMTP TLS reporting record",
)),
(_, RecordStatus::Invalid) => Some(Finding::new(
code,
Outcome::Warning,
Certainty::Conclusive,
"the domain publishes multiple recognizable security records",
)),
_ => None,
}
}
#[cfg(test)]
mod tests {
use futures_executor::block_on;
use super::*;
#[test]
fn duplicate_policy_records_are_invalid() {
let status = record(
TextRecords::new(
vec!["v=DMARC1; p=none".into(), "v=DMARC1; p=reject".into()],
None,
),
"v=dmarc1",
);
assert_eq!(status, RecordStatus::Invalid);
}
#[test]
fn identical_policy_records_remain_invalid() {
let status = record(
TextRecords::new(
vec!["v=DMARC1; p=reject".into(), "v=DMARC1; p=reject".into()],
None,
),
"v=dmarc1",
);
assert_eq!(status, RecordStatus::Invalid);
}
#[test]
fn near_match_is_not_a_security_record() {
let status = record(
TextRecords::new(vec!["v=spf10 include:example.com".into()], None),
"v=spf1",
);
assert_eq!(status, RecordStatus::Absent);
}
#[test]
fn version_tag_must_start_the_record() {
let status = record(
TextRecords::new(vec![" v=DMARC1; p=reject".into()], None),
"v=dmarc1",
);
assert_eq!(status, RecordStatus::Absent);
}
#[test]
fn text_lookups_obey_the_dns_deadline() {
struct StalledResolver;
impl crate::dns::Resolver for StalledResolver {
fn resolve(&self, _domain: &str) -> crate::dns::Resolve<'_> {
Box::pin(std::future::pending())
}
fn resolve_text(&self, _domain: &str) -> crate::dns::ResolveText<'_> {
Box::pin(std::future::pending())
}
}
struct ImmediateTimer;
impl crate::runtime::Timer for ImmediateTimer {
fn sleep(&self, _duration: std::time::Duration) -> crate::runtime::Sleep {
Box::pin(std::future::ready(()))
}
}
let network = Network::new(StalledResolver, ImmediateTimer);
let posture = block_on(inspect(
&network,
"example.com",
std::time::Duration::from_secs(1),
));
assert_eq!(posture.spf(), RecordStatus::Unavailable);
assert_eq!(posture.dmarc(), RecordStatus::Unavailable);
assert_eq!(posture.mta_sts(), RecordStatus::Unavailable);
assert_eq!(posture.tls_rpt(), RecordStatus::Unavailable);
}
}